This page provides the essentials for working with Git and GitHub with the goal of contributing specifically to MAAS documentation. See the upstream projects for definitive documentation: Git docs and GitHub docs.
Several actions are required before you can begin. These only need to be done once.
- GitHub account
- User environment
- Fork the MAAS docs repository on GitHub
- Clone your MAAS docs fork locally
- Add the upstream remote
A GitHub account will be required.
Verify your email address by responding to the email notification you will receive.
The remainder of this page will refer to your GitHub username as $GH_USERNAME (e.g. 'johnsmith').
Configure some user environment essentials.
Set your user name and email address:
git config --global user.name "$FIRST_NAME $LAST_NAME" git config --global user.email "$EMAIL_ADDRESS"
Pre-empt a later warning about how "pushes" should work:
git config --global push.default simple
When you send changes to GitHub you will need to authenticate. By default, your GitHub login credentials are used. Consider setting a credentials cache time limit beyond the default (15 min). Below it is set at 60 min:
git config --global credential.helper 'cache --timeout=3600'
To authenticate via SSH keys click on 'Settings' in the top-right corner, choose 'SSH and GPG keys' in the left menu, and add your public key.
A copy of the main (upstream) MAAS docs repository will be needed. This will become your working area. All your changes will be put there and then merged into the upstream repo. Branches of proposed changes are never created in the upstream repository directly. This copy is known as a fork.
Go to the MAAS docs repository now and fork it by pressing the Fork button in the top-right area:
The URL of your fork will become:
A clone is a local copy of a repository, including all metadata and history (commits, merges, etc). Since you cannot make changes in GitHub itself (where your fork currently resides) a copy of your fork will be needed on your local computer. Clone your fork now:
git clone https://github.com/$GH_USERNAME/maas-docs $GH_USERNAME-maas-docs
Alternatively, if you will be using SSH for authentication, clone in this way:
git clone firstname.lastname@example.org:$GH_USERNAME/maas-docs $GH_USERNAME-maas-docs
A directory called
$GH_USERNAME-maas-docs will be created. This is the clone
Add a remote to your local repository. This links it with the upstream version of the documentation, making it easy to keep your local branches in sync with upstream:
cd $GH_USERNAME-maas-docs git remote add upstream https://github.com/CanonicalLtd/maas-docs
If you're a serious contributor you should add the upstream series branches and track them. This will enable you to target specific series.
Get all data for the upstream repository using the fetch command. The first time you do this the upstream series branches will be exposed:
git fetch upstream
From https://github.com/CanonicalLtd/maas-docs * [new branch] 2.0 -> upstream/2.0 * [new branch] 2.1 -> upstream/2.1 * [new branch] 2.2 -> upstream/2.2 * [new branch] devel -> upstream/devel * [new branch] master -> upstream/master
Based on the above example output, branches '2.0', '2.1', '2.2', and 'devel' need to be tracked (this is done for 'master' by default):
git branch 2.0 upstream/2.0 git branch 2.1 upstream/2.1 git branch 2.2 upstream/2.2 git branch devel upstream/devel
Your GitHub fork inherited these tracking branches when it was created. This can be confirmed here:
Finally, we need to change the remote for these newly tracked branches as they are currently using 'upstream':
git branch -vv
2.0 bb0fb27 [upstream/2.0] Merge pull request #394 from pmatulis/cherrypick-pr383+384-to-2.0 2.1 78e3ebb [upstream/2.1] Merge pull request #428 from pmatulis/cherrypick-pr426-to-2.1 2.2 55527e1 [upstream/2.2] Merge pull request #433 from pmatulis/cherrypick-pr432-to-2.2 devel 030cae8 [upstream/devel] Merge pull request #410 from pmatulis/backport-master-to-devel * master df32fa1 [origin/master] Merge pull request #432 from * pmatulis/clarify-reserved-ip-ranges
This is not ideal. Change their remotes to 'origin':
git branch -u origin/2.0 2.0 git branch -u origin/2.1 2.1 git branch -u origin/2.2 2.2 git branch -u origin/devel devel
A less verbose command is typically used to list branches:
2.0 2.1 2.2 devel * master
Over time, contribution branches will come and go but the ones above should be regarded as permanent.
You will need to track a series branch as they become available upstream (approximately every 6 months). Continuing with the example above, we will demonstrate using the 2.3 series branch:
git fetch upstream git branch 2.3 upstream/2.3
However, because your GitHub fork will not contain the new branch you cannot instruct Git to use the origin (fork) branch as the remote. You will first need to push the new branch to your fork and then change it. This can be done with one command:
git push -u origin 2.3
You should now have remotes for both the upstream repository and your fork (known as origin to git):
git remote -v
The output should look like:
origin https://github.com/$GH_USERNAME/maas-docs (fetch) origin https://github.com/$GH_USERNAME/maas-docs (push) upstream https://github.com/CanonicalLtd/maas-docs (fetch) upstream https://github.com/CanonicalLtd/maas-docs (push)
To sync one of your fork's series branches (both locally and on GitHub), call it $SERIES_BRANCH, with the corresponding upstream branch:
git fetch upstream # Get all current data on the upstream repository git checkout $SERIES_BRANCH # Move in to your local branch git merge --ff-only upstream/$SERIES_BRANCH # Sync your local branch with the upstream branch git push origin $SERIES_BRANCH # Sync your GitHub branch with your now-updated local branch
Decide which series branch you want to target (make an improvement to). Choose the most recent one that applies (often 'master' but not necessarily). The changes, if they're deemed important enough, will be backported to earlier series for you by the Doc team. Let this branch be called $TARGET_SERIES_BRANCH.
Enter the clone directory and sync $TARGET_SERIES_BRANCH with upstream as previously described.
Create a branch that will contain your changes (replace $NEW_BRANCH with your arbitrarily-named branch):
git checkout -b $NEW_BRANCH $TARGET_SERIES_BRANCH
Edit some files with your favourite editor. See the Writing guide.
Verify the HTML by building the docs locally. See Building the docs.
Check which files have been added or modified:
Add those files to the repository. For example:
git add en/manage-ha.md
git add media/add-zone.png
Make a commit to save your changes locally:
git commit -m "a message which describes the change"
Push the branch to your fork on GitHub:
git push origin $NEW_BRANCH
You can push your changes to GitHub at any time (i.e. you do not need to have finished your intended work). Indeed, doing so can be a form of off-disk backup.
Create a PR. In GitHub, your branches are listed here:
Find $NEW_BRANCH and press the 'New pull request' button. You should see the following:
- base fork:
CanonicalLtd/maas-docs- This is what you want, always.
master- This is the $TARGET_SERIES_BRANCH.
- head fork:
pmatulis/maas-docs- This is the fork belonging to $GH_USERNAME of 'pmatulis'.
readme-link-issue-423- This is $NEW_BRANCH.
All the changes will be shown lower down. The red and green backgrounds represent removed and added content respectively. Look over this carefully.
When you're ready, click on the green 'Create pull request' button. A new window will appear where you can edit the PR title and add a comment summarizing the changes. Also, if the PR fixes a filed issue , say #423, include a line in the comment:
Fixes #423(when the PR is merged the issue will be automatically closed).
Press the 'Create pull request' button to finalize.
- base fork:
Wait for the Doc team to review your PR. Some changes may be asked of you. If so, don't panic, just repeat the process:
- Edit within $NEW_BRANCH
- Add the modified files
- Commit (with an appropriate message)
There is no need to update the PR; GitHub will do this for you.
Once the PR is merged, branch $NEW_BRANCH should be removed from both your GitHub fork and your local fork. There are various places to do the former in GitHub and both can be done via