Make a Change Using a Local Clone

If you are going to make a lot of changes, you can fork the spinnaker/spinnaker.github.io repository and work from a local clone. Make sure you have git installed on your computer and have configured your GitHub account. See the GitHub Help for details.

Fork the Spinnaker documentation repository

  1. Navigate to the spinnaker/spinnaker.github.io repository with a web browser.
  2. Click Fork.

Create a local repository and set the upstream repository

  1. In a terminal window, clone your fork:

    git clone git@github.com:<github-username>/spinnaker.github.io.git
    
  2. Navigate to the new spinnaker.github.io directory. Set the spinnaker/spinnaker.github.io repository as the upstream remote:

    cd spinnaker.github.io
    
    git remote add upstream https://github.com/spinnaker/spinnaker.github.io.git
    
  3. Confirm your origin and upstream repositories:

    git remote -v
    

    Output is similar to:

    origin	git@github.com:<github-username>/spinnaker.github.io.git (fetch)
    origin	git@github.com:<github-username>/spinnaker.github.io.git (push)
    upstream	https://github.com/spinnaker/spinnaker.github.io.git (fetch)
    upstream	https://github.com/spinnaker/spinnaker.github.io.git (push)
    

Update your local repository

Make sure your local repository is current before you start making changes. Fetch commits from your fork’s origin/master and spinnaker/spinnaker.github.io’s upstream/master:

   git fetch origin
   git fetch upstream

Create a working branch

  1. Make sure you are in your master branch before you create your working branch. You can use git branch to see which branch you are in.

     git branch
    

    The output lists your local branches. There is an * next to the branch you are in.

    working-branch-1
    working-branch-2
    * master
    

    If you are not in master, execute git checkout master to go to your master branch. See the Understanding history: What is a branch? section of the Git User Manual for more information.

  2. Create a new working branch based on upstream/master.

    git checkout -b <your-working-branch> upstream/master
    

    Since git tracks changes to upstream\master, you don’t need to rebase your fork before you create a working branch.

  3. Make your changes.

Use the git status command at any time to see what files you’ve changed.

Preview your changes locally

It’s a good idea to preview your changes locally before opening a pull request (PR). A preview lets you catch build errors or markdown formatting problems. The easiest way to deploy the documentation site is with a Docker container built using the included Dockerfile. Make sure you have Docker installed on your computer. Run the following commands from the spinnaker.github.io directory:

docker build --tag spinnaker/spinnaker.github.io-test .
docker run -it --rm --mount "type=bind,source=$(pwd),target=/code" \
    -p 4000:4000 spinnaker/spinnaker.github.io-test --incremental

Alternately, if you have Jekyll installed, you can generate the site by executing:

bundle exec jekyll serve --watch --incremental

Navigate to http://localhost:4000 to see your changes.

Commit your changes

  1. Check which files you need to commit:

    git status
    

    Output is similar to:

    On branch <your-working-branch>
    Changes not staged for commit:
    (use "git add <file>..." to update what will be committed)
    (use "git restore <file>..." to discard changes in working directory)
    
    modified:   _data/navigation.yml
    
    Untracked files:
    (use "git add <file>..." to include in what will be committed)
    
    community/contributing/docs/local-clone.md
    
    no changes added to commit (use "git add" and/or "git commit -a")
    
  2. Add new files listed under Untracked files to the commit:

    git add <path/your-file-name>
    

    Repeat this for each new file.

  3. Create a commit:

    git commit -a -m "<your-commit-subject>" -m "<your-commit-description>"
    
    • -a: Commit all staged changes.
    • -m: Use the given <your-commit-subject> as the commit message. If multiple -m options are given, their values are concatenated as separate paragraphs.

    Your commit messages must be 50 characters or less. Do not use any GitHub Keywords in your commit message. You can add those to the pull request description later.

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

    git push origin <your-working-branch>
    

    You can commit and push many times before you create your PR.

Create a pull request from your fork to spinnaker/spinnaker.github.io

  1. In a web browser, go to the spinnaker/spinnaker.github.io repository. You should see your recently pushed working branch with a Compare & pull request button.

    CompareAndPullRequest

  2. Click Compare & pull request. This takes you to the Open a pull request screen.

    OpenPullRequest

    1. The Title defaults to the commit subject. Update the title so it follows the <type>(<scope>): <subject> format. Make sure you include a space after the colon. For example:

      docs(plugins): add documentation for plugin creators
      

      The Spinnaker repositories use a PR title checker, so your PR will fail if the title is not in the correct format. For more information, see commit message conventions.

    2. The Leave a comment field defaults to the commit description. Pull request descriptions are the first step to helping reviewers and project maintainers understand why your change was made. Do not leave this field blank. Provide as much description as possible. A good description helps get your PR merged faster!
    3. Leave the Allow edits from maintainers checkbox selected.
  3. Click the Create pull request button.

Congratulations! You can view your submitted pull request on the Pull requests tab.

Do not delete your working branch until your pull request has been merged! You may need to update your content based on reviewer feedback.

When you look at your PR, you may see a This branch is out-of-date with the base branch message. This means approvers merged PRs while you were working on your changes. If you see a Merge conflict message, you need to rebase your PR.

Addressing feedback locally

Reviewers may ask you to make changes to your pull request. Read the feedback and make changes in your working branch.

  1. After making your changes, create a new commit:

    git commit -a -m "<your-commit-subject>" -m "<your-commit-description>"
    
  2. Push your changes:

    git push origin <your-working-branch>
    

Changes from reviewers

Sometimes reviewers commit changes to your pull request. Fetch those commits before making any other changes.

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

    git fetch origin
    git rebase origin/<your-working-branch>
    
  2. After rebasing, force-push new changes to your fork:

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

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 working branch:

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

    Then force-push the changes to your fork:

    git push --force-with-lease origin <your-working-branch>
    
  2. Fetch changes from spinnaker/spinnaker.github.io’s upstream/master and rebase your branch:

    git fetch upstream
    git rebase upstream/master
    
  3. Inspect the results of the rebase:

    git status
    

This results in a number of files marked as conflicted.

  1. 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.

  2. Add the files to the changeset:

    git add <filename>
    
  3. Continue the rebase:

   git rebase --continue
  1. Repeat steps 2 to 5 as needed.

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

  1. Force-push your working branch to your remote fork:

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

    The pull request no longer shows any conflicts.

For more information, see Git Branching - Basic Branching and Merging, Advanced Merging, or ask in the #sig-documentation Slack channel for help.