Proposing changes

Getting started

1. Familiarize yourself with the documentation repository and the website’s static site generator (Hugo).
2. Understand the process for opening a pull request and reviewing changes

Opening a pull request

To contribute new pages or improve existing pages, open a pull request (PR).

If your change is small, or you’re unfamiliar with git, read Changes using GitHub.

Changes using GitHub

If you’re less experienced with git workflows, here’s an easier method of opening a pull request.

1. On the page you want to modify, select the pencil icon at the top right.

2. Make your changes in the GitHub markdown editor.

3. Below the editor, fill in the Propose file change form.

   In the first field, give your commit message a title. In the second field provide a description

   Warning

   Do not use any GitHub Keywords in your commit message. You can add those to the pull request description later.

4. Select Propose file change.

5. Select Create pull request.

6. The Open a pull request screen appears. Fill in the form:

   • The Subject field of the pull request defaults to the commit summary. You can change it if needed.
   • The Body contains your extended commit message, if you have one, and some template text. Add the details the template text asks for, then delete the extra template text.
   • Leave the Allow edits from maintainers checkbox selected.
   PR descriptions are a great way to help reviewers understand your change. For more information, see Opening a PR.

7. Select Create pull request.

Addressing feedback in GitHub

Before merging a pull request, community members review and approve it.

If a reviewer asks you to make changes:

1. Go to the Files changed tab.
2. Select the pencil (edit) icon on any files changed by the pull request.
3. Make the changes requested.
4. Commit the changes.

Work from a local fork

If you’re more experienced with git, or if your changes are larger than a few lines, work from a local fork.

Fork the fluxcd/website repository

1. Navigate to the fluxcd/website repository.

2. Select Fork.

3. Navigate to the new website directory. Set the fluxcd/website repository as the upstream remote:

   cd website
   
   git remote add upstream https://github.com/fluxcd/website.git
   

4. Confirm your origin and upstream repositories:

   git remote -v
   

   Output is similar to:

   origin    git@github.com:<github_username>/website.git (fetch)
   origin    git@github.com:<github_username>/website.git (push)
   upstream  https://github.com/fluxcd/website.git (fetch)
   upstream  https://github.com/fluxcd/website.git (push)
   

5. Fetch commits from your fork’s origin/main and fluxcd/website’s upstream/main:

   git fetch origin
   git fetch upstream
   

   This makes sure your local repository is up to date before you start making changes.

6. Create a new branch based on upstream/main:

   git checkout -b <my_new_branch> upstream/main
   

7. Make your changes using a text editor.

At any time, use the git status command to see what files you’ve changed.

Commit your changes

When you are ready to submit a pull request, commit your changes.

1. In your local repository, check which files you need to commit:

   git status
   

   Output is similar to:

   On branch <my_new_branch>
   Your branch is up to date with 'origin/<my_new_branch>'.
   
   Changes not staged for commit:
   (use "git add <file>..." to update what will be committed)
   (use "git checkout -- <file>..." to discard changes in working directory)
   
   modified:   content/en/contribute/new-content/run-locally.md
   
   no changes added to commit (use "git add" and/or "git commit -a")
   

2. Add the files listed under Changes not staged for commit to the commit:

   git add <your_file_name>
   

   Repeat this for each file.

3. After adding all the files, create a commit:

   git commit -sm "Your commit message"
   

   Do not use any GitHub Keywords in your commit message. You can add those to the pull request description later.

4. Push your local branch and its new commit to your remote fork:

   git push origin <my_new_branch>
   

Open a pull request from your fork to fluxcd/website

1. In a web browser, go to the fluxcd/website repository.
2. Navigate to pull requests and select New pull request
3. Select compare across forks
4. From the head repository drop-down menu, select your fork.
5. From the compare drop-down menu, select your branch.
6. Select Create Pull Request.
7. Add a description for your pull request:
   • Title (50 characters or less): Summarize the intent of the change.
   • Description: Describe the change in more detail.
     • If there is a related GitHub issue, include Fixes #12345 or Closes #12345 in the description. GitHub’s automation closes the mentioned issue after merging the PR if used. If there are other related PRs, link those as well.
     • If you want advice on something specific, include any questions you’d like reviewers to think about in your description.
8. Select the Create pull request button.

Congratulations! Your pull request is available in Pull requests.

Addressing feedback locally

1. After making your changes, amend your previous commit:

   git commit -as --amend
   

   • -as: commits all changes and adds your signoff
   • --amend: amends the previous commit, rather than creating a new one

2. Update your commit message if needed.

3. Use git push origin <my_new_branch> to push your changes and re-run the Netlify tests.

Changes from reviewers

Sometimes reviewers commit to your pull request. Before making any other changes, fetch those commits.

1. Fetch commits from your remote fork and rebase your working branch:

   git fetch origin
   git rebase origin/<your-branch-name>
   

2. After rebasing, force-push new changes to your fork:

   git push --force-with-lease origin <your-branch-name>
   

Adding DCO on commits retroactively

1. Open an interactive rebase session

   git rebase --signoff HEAD~<number of commits in your pr>
   

2. Verify you have signed the commits

   git log
   

3. Force push

   git push -f origin branchname
   

Merge conflicts and rebasing

If another contributor commits changes to the same file in another PR, it can create a merge conflict. You must resolve all merge conflicts in your PR.

1. Update your fork and rebase your local branch:

   git fetch origin
   git rebase origin/<your-branch-name>
   

   Then force-push the changes to your fork:

   git push --force-with-lease origin <your-branch-name>
   

2. Fetch changes from fluxcd/website’s upstream/main and rebase your branch:

   git fetch upstream
   git rebase upstream/main
   

3. Inspect the results of the rebase:

   git status
   

   This results in a number of files marked as conflicted.

4. Open each conflicted file and look for the conflict markers: >>>, <<<, and ===. Resolve the conflict and delete the conflict marker.

   For more information, see How conflicts are presented.

5. Add the files to the changeset:

   git add <filename>
   

6. Continue the rebase:

   git rebase --continue
   

7. Repeat steps 2 to 5 as needed.

   After applying all commits, the git status command shows that the rebase is complete.

8. Force-push the branch to your fork:

   git push --force-with-lease origin <your-branch-name>
   

   The pull request no longer shows any conflicts.