- In a Nutshell
- How to Fork From Us
- Keep Track of Updates
- Pull Requests or Being Social
- Maintainer Notes
to do list:
- coding guide lines, styles/fileHeaders/...
- commit rules
- compile suite movie -> COMMIT.md
- git for svn users
- explain pull requests
If you are familiar with git, feel free to jump to our github workflow section.
Debian/Ubuntu:
sudo apt-get install git
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
- you may like to visit http://mac.github.com/
Windows:
- see here
- just kidding, it's this link
- please use UTF8 for your files and take care of line endings
Configure your global git settings:
git config --global user.name NAMEgit config --global user.email [email protected]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.st "status -sb"(short status version)git config --global alias.l "log --oneline --graph --decorate --all"(branch history)git config --global rerere.enable 1(see git rerere)
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.
- git - the simple guide
- 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 <[email protected]>"
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.)
Welcome to github! We will try to explain our coordination strategy (I am out of here!) and our development workflow in this section.
Create a GitHub account and prepare your basic git config.
Prepare your forked copy of our repository:
- fork picongpu on GitHub
git clone [email protected]:<YourUserName>/picongpu.git(create local copy)git remote add mainline [email protected]: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 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.
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.gitgit 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 <yourFeatureName> and apply your
changes there.
We consider it a best practice not to modify your master branch branch at
all. Instead you can use it to pull 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!
How to propose that your awesome feature (we know it will be awesome!) should be included in the mainline PIConGPU version?
Due to the so called
pull requests
in GitHub, this quite easy (yeah, sure). We start again with a
forked repository of our own. You already created a new feature branch
starting from our dev branch and commited your changes. Finally, you
pushed
your local branch to your GitHub repository: git push -u origin <yourLocalBranchName>
Now let's start a review. Open the GitHub homepage, go to your repository and switch to your pushed feature branch. Select the green compare & review button. Now compare the changes between your feature branch and our dev.
Everything looks good? Submit it as a pull request (link in the header).
Afterwards, a fruitful ( wuhu, we love you - don't be scared ) discussion about your submitted change set will start. If we find some things you could improve ( That looks awesome, all right! ), simply change your local feature branch and push the changes back to your GitHub repository, to update the pull request.
As a best practive agreement, we wait for at least two of our maintainers to review the pull request until it is merged.
Sharing is caring! Thank you for participating, you are great!
- 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.
Well - there are some! ;)
- coming soon (in a separate file)
Please add the according license header snippet to your new files:
- for PIConGPU (GPLv3+):
src/tools/bin/addLicense <FileName> - for libraries (LGPLv3+ & GPLv3+):
export PROJECT_NAME=libgpugrid && src/tools/bin/addLicense <FileName> - delete other headers:
src/tools/bin/deleteHeadComment <FileName> - add license to all .hpp files within a directory (recursive):
export PROJECT_NAME=PIConGPU && src/tools/bin/findAndDo <PATH> "*.hpp" src/tools/bin/addLicense - the default project name ist
PIConGPU(case sensitive!) and adds the GPLv3+ only.
See our commit rules page
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!