How to Participate as a Developer
Contents
Code - Version Control
If you are familiar with git, feel free to jump to our github workflow section.
install git
Debian/Ubuntu:
sudo apt-get install git
make sure
git --version
is at least at version 1.7.10
Optional one of these. There are nice GUI tools available to get an overview on your repository.
gitk git-gui qgit gitg
Mac:
see here
Windows:
see here
just kidding, it’s this link
please use ASCII for your files and take care of line endings
Configure your global git settings:
git config --global user.name NAME
git config --global user.email EMAIL@EXAMPLE.com
git config --global color.ui "auto"
(if you like colors)git config --global pack.threads "0"
(improved performance for multi cores)
You may even improve your level of awesomeness by:
git config --global alias.pr "pull --rebase"
(see how to avoide merge commits)git config --global alias.pm "pull --rebase mainline"
(to sync with the mainline bygit pm dev
)git config --global alias.st "status -sb"
(short status version)git config --global alias.l "log --oneline --graph --decorate --first-parent"
(single branch history)git config --global alias.la "log --oneline --graph --decorate --all"
(full branch history)git config --global rerere.enable 1
(see git rerere)More
alias
tricks:git config --get-regexp alias
(show all aliases)git config --global --unset alias.<Name>
(unset alias<Name>
)
git
Git is a distributed version control system. It helps you to keep your software development work organized, because it keeps track of changes in your project. It also helps to come along in teams, crunching on the same project. Examples:
Arrr, dare you other guys! Why did you change my precious main.cpp, too!?
Who introduced that awesome block of code? I would like to pay for a beer as a reward.
Everything is wrong now, why did this happen and when?
What parts of the code changed since I went on vacation (to a conference, phd seminar, mate fridge, …)?
If version control is totally new to you (that’s good, because you are not spoiled) - please refer to a beginners guide first.
15 minutes guide at try.github.io
Since git is distributed, no one really needs a server or services like github.com to use git. Actually, there are even very good reasons why one should use git even for local data, e.g. a master thesis (or your collection of ascii art dwarf hamster pictures).
Btw, fun fact warning: Linus Torvalds, yes the nice guy with the pinguin stuff and all that, developed git to maintain the Linux kernel. So that’s cool, by definition.
A nice overview about the humongous number of tutorials can be found at stackoverflow.com … but we may like to start with a git cheat sheet (is there anyone out there who knows more than 1% of all git commands available?)
git-tower.com (print the 1st page)
github.com - “cheat git” gem (a cheat sheet for the console)
kernel.org Everyday GIT with 20 commands or so
an other interactive, huge cheat sheet (nice overview about stash - workspace - index - local/remote repositories)
Please spend a minute to learn how to write useful git commit messages (caption-style, maximum characters per line, use blank lines, present tense). Read our commit rules and use keywords.
If you like, you can credit someone else for your next commit with:
git commit --author "John Doe <johns-github-mail@example.com>"
git for svn users
If you already used version control systems before, you may enjoy the git for svn users crash course.
Anyway, please keep in mind to use git not like a centralized version control system (e.g. not like svn). Imagine git as your own private svn server waiting for your commits. For example Github.com is only one out of many sources for updates. (But of course, we agree to share our finished, new features there.)
GitHub Workflow
Welcome to github! We will try to explain our coordination strategy (I am out of here!) and our development workflow in this section.
In a Nutshell
Create a GitHub account and prepare your basic git config.
Prepare your forked copy of our repository:
fork picongpu on GitHub
git clone git@github.com:<YourUserName>/picongpu.git
(create local copy)git remote add mainline git@github.com:ComputationalRadiationPhysics/picongpu.git
(add our main repository for updates)git checkout dev
(switch to our, its now your, dev branch to start from)
Start a topic/feature branch:
git checkout -b <newFeatureName>
(start a new branch from dev and check it out)hack hack
git add <yourChangedFiles>
(add changed and new files to index)git clang-format
(format all changed files with the clang-format utility, needs to be loaded or installed separately)git add <yourChangedFiles>
(add the formating changes)git commit
(commit your changes to your local repository)git pull --rebase mainline dev
(update with our remote dev updates and avoid a merge commit)
Optional, clean up your feature branch. That can be dangerous:
git pull
(if you pushed your branch already to your public repository)git pull --rebase mainline dev
(apply the mainline updates to your feature branch)git log ..mainline/dev
,git log --oneline --graph --decorate --all
(check for related commits and ugly merge commits)git rebase mainline/dev
(re-apply your changes after a fresh update to themainline/dev
, see here)git rebase -i mainline/dev
(squash related commits to reduce the complexity of the features history during a pull request)
Publish your feature and start a pull request:
git push -u origin <newFeatureName>
(push your local branch to your github profile)Go to your GitHub page and open a pull request, e.g. by clicking on compare & review
Add additional updates (if requested to do so) by
push
-ing to your branch again. This will update the pull request.
How to fork from us
To keep our development fast and conflict free, we recomment you to fork our repository and start your work from our dev (development) branch in your private repository. Simply click the Fork button above to do so.
Afterwards, git clone
your repository to your
local machine.
But that is not it! To keep track of the original dev repository, add
it as another remote.
git remote add mainline https://github.com/ComputationalRadiationPhysics/picongpu.git
git checkout dev
(go to branch dev)
Well done so far! Just start developing. Just like this? No! As always in git,
start a new branch with git checkout -b topic-<yourFeatureName>
and apply your
changes there.
Keep track of updates
We consider it a best practice not to modify your dev branch at all.
Instead you can use it to pull --ff-only
new updates from
the original repository. Take care to switch to dev by git checkout dev
to start
new feature branches from dev.
So, if you like to do so, you can even
keep track
of the original dev branch that way. Just start your new branch with
git branch --track <yourFeatureName> mainline/dev
instead. This allows you to immediatly pull or fetch from our dev and
avoids typing (during git pull --rebase
). Nevertheless, if you like to push
to
your forked (== origin
) repository, you have to say e.g.
git push origin <branchName>
explicitly.
You should add updates from the original repository on a regular basis or at least when you finished your feature.
commit your local changes in your feature branch:
git commit
Now you could do a normal merge of the latest mainline/dev
changes into
your feature branch. That is indeed possible, but will create an ugly
merge commit.
Instead try to first update the point where you branched from and apply
your changes again. That is called a rebase and is indeed less harmful as
reading the sentence before:
git checkout <yourFeatureName>
git pull --rebase mainline dev
(in case of an emergency, hitgit rebase --abort
)
Now solve your conflicts, if there are any, and you got it! Well done!
maintainer notes
do not push to the main repository on a regular basis, use pull request for your features like everyone else
never do a rebase on the mainline repositories (this causes heavy problems for everyone who pulls them)
on the other hand try to use pull –rebase to avoid merge commits (in your local/topic branches only)
do not vote on your own pull requests, wait for the other maintainers
we try to follow the strategy of a-successful-git-branching-model
Last but not least, help.github.com has a very nice FAQ section.
More best practices.
Commit Rules
See our commit rules page
Test Suite Examples
You know a useful setting to validate our provided methods? Tell us about it or add it to our test sets in the examples/ folder!