Skip to content

Git Contributor Workflow

Jump to bottom
Alexander V. Wolf edited this page Jan 29, 2024 · 11 revisions

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):

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 a git reset --hard upstream master.

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

1: Create 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 or issue/0123.

git checkout -b myBranchName

2: Commit 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.

3: Push 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 in your public GitHub repository, create a pull request with a good title and description.

4: 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

Note: if you need to submit several unrelated changes, you have to start from the official master every time. Either you wait for your PR to be merged to the remote master, or you start again from the latest master at your disposition. Do not create new branches from your own branches unless you know exactly what you are doing.

Handling Pull Requests

(Note to ourselves)

For proper testing pull requests before merge you may change the setting up your Git repository to use simple command, similar:

git checkout pr/567

To get this behavior please open file .git/config in the Git repository and edit the section [remote "origin"]. For Stellarium developers it should be:

[remote "origin"]
	url = [email protected]:Stellarium/stellarium.git
	fetch = +refs/heads/*:refs/remotes/origin/*
	fetch = +refs/pull/*/head:refs/remotes/origin/pr/*

There is no need to clone contributors' repos; essence is to ingest the PR branches.

See the page 173 in "Pro Git" book for details.

Handling Commit Messages

(Note to ourselves)

We're configured GitHub actions to handling some special keys (keywords) in commit messages to activate specific doings:

  • [publish] is used to activating a process of building a downloadable installer package for Windows (a full and patch packages) on the AppVeyor (installers can be download in artifacts section) and downloadable AppImage packages for linux via GH actions.
  • [ci skip] (or [skip ci]) is used to skipping a process of building source code and running unit tests (all commits from Transifex user are skipped by CI instances too).
  • [qt5] is used to activating a process of building and running unit tests in Qt5-based instances of linux, macOS and xBSD systems

Debugging

Use the debugger in QtCreator if necessary. If symbols are listed as "inaccessible", check to switch off "Python dumper" in (Tools > Options > Debugger > CDB Tab > Use Python dumper). See Qt forum

Clone this wiki locally