The Unwritten Rules for Github by devdiscuss
Kim Arnett Nov 19, 2017
A while back a #devdiscuss post by @ThePraticalDev sparked a great discussion on the advice users have for getting the most out of Github. Either for personal use, team use, open source, career advancement and more. I took the liberty to compile some of the best advice and write this post.
The first topic I was interested in was branching. At the time, I was getting started on a project that had 30+ branches, mostly abandoned. My first question was, what is the proper way to use branches? What works best? Do they work well at all?
Everyone seemed to agree that branches were the way to go. Here’s the original post with the credit to the following advice, since much of the same advice was recommended multiple times, the credit deserves to be shared.
- Create a branch for every new feature, and delete the branch once the feature is merged into main.
- Rebase master often to keep merging pain free.
- Create a branch for proof of concept work.
- Create a branch for incomplete features when you have to switch focus to another project.
- Git Flow was mentioned a few times. Not knowing much about it, I’ll leave you with this tutorial.
- Bug fixes and refactoring should also be done in a branch.
- Having branches for development and production is also a good practice. Production branch will mostly be untouched other than deployments from the development branch.
- Branches can be any size.
- Pull requests allow you to track code changes even after the branch has been deleted.
- Tag releases.
- Use code reviews to ensure quality.
- Branches should have the same test coverage as master / trunk.
Worth noting a few people don’t use the branching feature, but most feedback indicated they were the way to go. Although no elaboration was given, based on my experience alone, if only a few people are working on the project, and they’re all working on different parts with very little overlapping – you can get away without branches with very little pain. However, the larger your team and or codebase grows, the more you can get out of using branching.
- Get to know the people working on the code, learn their names, join the slack, get to know them and ask for help when you need it.
- If you’re not sure where to start – even flagging parts of the readme / documentation that is confusing or seems incomplete, is helpful. Collaborate with people across the world and expose yourself to different coding styles.
- Pull Request everything.
- Publish what you’re learning
- If you’re giving talks, put the code, slides, notes all on Github
- Public code helps you understand Git workflow even if it’s only you. Also helps keep a conscious effort to create clean code.
- Build something, any size, with clean code, tests, comments, all the stops to show your capabilities.
Other / General
- Don’t blindly accept code reviews, leave a comment about what you verified – even if its as simple as code you like or dislike.
- Don’t EVER post private keys / api keys / certificates.
- Integrate linters and code checkers
- Integrate Continuous Integration (CI) for building software.
- Use descriptive commit messages and pull request messages.
- Tag your commit messages with the ticket number it corresponds with.
Do you have any to add?
Originally posted on KaydaCode