Everyone will tell you something different about how to setup a git project and how to establish contribution policies. But there is a certain way I like to setup group projects in git (whether it's GitHub, BitBucket, or GitLab makes no difference) that works for me, and you are welcome to use it as well. Or not. It's okay if we disagree.
I make the main project (the one I would advertise, issue releases from, etc.) from a group or organization account. There are two reasons for this. First, I think it looks more professional to have a group or organization account, rather than just being a project from some guy on the Internet (however, personal repositories are fine for smaller or single-person projects. The second reason is that I like the project contributors to build in their own fork.
I like to have each contributor work in their own fork of the project: It makes it easier to ensure the main repository stays clean; it allows contributors to veer off on side tasks that won't make it into the main project for a long time; and it makes it easier to lock down merges into the main branch (since it's under different accounts).
The primary project repository should have two branches if you are developing source code: master and devel. The master branch should change infrequently; the devel branch more frequently. Version releases will be tagged from the master branch, but little else should happen there.
Have your project contributors submit pull requests to the devel branch of the group/org repo to incorporate changes into the main project. Also, if your contributors have a "commit early, commit often" policy like I do, you might recommend that they squash commits using rebase, in order to make the pull request a bit cleaner and easier to review.
When possible, you should hold review meetings on a regular basis (weekly or biweekly, depending on how many contributors you have) to discuss proposed additions to the main repository. These requests should be made via pull request to the devel branch of the group repository.
When it's time to release a new version of your code, I usually take the following approach:
Using this approach, the master branch stays fully functional, and the devel branch is immediately available for further upstream development.
I hope my approach to distributed development using git is either an approach you can take for your own group software projects, or you can at least get a few good ideas to incorporate into your next development adventure.
Please feel free to comment below, don't forget to sign up for updates delivered directly to your inbox, and as always feel free to follow me on Twitter and LinkedIn.
Starting a Group/Org Project
I make the main project (the one I would advertise, issue releases from, etc.) from a group or organization account. There are two reasons for this. First, I think it looks more professional to have a group or organization account, rather than just being a project from some guy on the Internet (however, personal repositories are fine for smaller or single-person projects. The second reason is that I like the project contributors to build in their own fork.
Have Each Contributor Fork the Main Project
I like to have each contributor work in their own fork of the project: It makes it easier to ensure the main repository stays clean; it allows contributors to veer off on side tasks that won't make it into the main project for a long time; and it makes it easier to lock down merges into the main branch (since it's under different accounts).
Keep a Master and a Devel Branch
The primary project repository should have two branches if you are developing source code: master and devel. The master branch should change infrequently; the devel branch more frequently. Version releases will be tagged from the master branch, but little else should happen there.
Have Contributors Submit Pull Requests
Have your project contributors submit pull requests to the devel branch of the group/org repo to incorporate changes into the main project. Also, if your contributors have a "commit early, commit often" policy like I do, you might recommend that they squash commits using rebase, in order to make the pull request a bit cleaner and easier to review.
Hold Review Meetings for Pull Requests
When possible, you should hold review meetings on a regular basis (weekly or biweekly, depending on how many contributors you have) to discuss proposed additions to the main repository. These requests should be made via pull request to the devel branch of the group repository.
Versioning and Releases
When it's time to release a new version of your code, I usually take the following approach:
- Stop accepting pull requests.
- Complete a set of unit tests on the devel branch (if you use automatic testing like Travis CI, this is MUCH easier).
- If the devel branch is working as expected (passing all of your tests), merge devel into master.
- Tag the master branch with the release version.
- Share with your users that you have released a new version!
Using this approach, the master branch stays fully functional, and the devel branch is immediately available for further upstream development.
I hope my approach to distributed development using git is either an approach you can take for your own group software projects, or you can at least get a few good ideas to incorporate into your next development adventure.
Please feel free to comment below, don't forget to sign up for updates delivered directly to your inbox, and as always feel free to follow me on Twitter and LinkedIn.