Git Contributor Workflow

Important notes:

1. Do not commit to master. Create your own branch and commit to it.
2. Be descriptive in your branch names, commit messages, and pull request title and descriptions.
3. Use git status often to check what branch you are on and see if you have any uncommitted changes.

Preparing your fork

Assuming you already have created your own fork and cloned it to your computer. Also, that you have configured the original Stellarium repository to upstream (see Step 3), that is:

git remote add upstream https://github.com/Stellarium/stellarium.git

Git workflow

Initially, make sure you are in the master branch and that it's in sync with upstream/master:

git checkout master
git pull upstream master

You should never touch your master branch, i.e., never make changes and create commits in the master branch. In this way, git pull should never invoke auto-merge commits. If it happens, stop! cancel the auto-merge commit and do git reset --hard upstream master.

The preferred Git workflow for contributing to Stellarium is as follows:

Creating a topic branch

Create a local branch from master called myBranchName (you can use any name you want, but try to use one that makes sense with your changes or refer to an issue number as issue123.

git checkout -b myBranchName

Committing your changes

After you finished your changes, use git add to add the changed files and git commit to create a local commit with all your changes. Check with git status that you don’t have any dirty files and uncommitted changes around.

Pushing your commits

Before pushing your branch, you should ensure that your changes merge cleanly with the main repository. For that, you need to pull all changes done by other developers in the meantime.

git checkout master
git pull upstream master
git checkout myBranchName
git rebase master

If you get conflicts, you will see lines with ">>>>" added to those files. Resolve those conflicts manually, add them and finish the rebase. Check with git status and/or gitk if the merge went well and the history now contains your changes.

After rebasing and before pushing, you need to re-test your branch because other contributions might have introduced new issues.

If all went well, push your changes to your remote fork.

git push origin myBranchName

Now that your changes are on GitHub, create a pull request with a good title and description.

After your Pull Request is accepted and merged

If your Pull Request was accepted and is merged into the main repository, you can now delete your topic branch (myBranchName).

git branch -d myBranchName
git push origin :myBranchName

Handling Pull Requests

(Note to ourselves)

See the progit.pdf book, page 173 for setting up your GIT for proper testing before merge. Then

git checkout pr/567

No need to clone contributors' repos.