I recently had to send an email to our customer (and their developers) regarding mostly git usage and general Ruby coding style on our project.
The list borrows standard concept from many places and experienced git users and ruby developers will most likely know most of its points, but I was told it would make a good blog post, so here is an adaptation of the email.
On Git commit history:
- Commit history is important, it’s even more important when we have a serious problem (IE: need to roll back changes for example). So make sure your commit messages are explanatory of what changes you introduce.
- Don’t be afraid to use
git commit --amendlocally, I for example tend to forget about it and commit a lot of ‘debugger’ lines. So what I do is delete the lines,
git add . && git commit --amendwill fix the commit, so it will never get to github. (Important Note: never ever do –amend after you have already pushed to github. Or stuff will get scary – if you do this you’ll need to force push to github later, and it’s possible that you delete commits by other people)
- Following the same reasoning: the first line of a commit message shouldn’t be longer than 50 characters. So as to keep it brief and easily parseable when you are reading through the commit history. If you need to talk more in detail about what you are doing (it happens a lot, and it’s not bad at all) do
-m, so it goes into vim, and then write a short first line, leave an empty line and then describe the commit more in detail.
- Don’t mix stuff, if you have a lot of changes do atomic commits only of the relevant files or else it gets really difficult to rollback only one feature, for example. Always think: “If I had to do a release NOW and this didn’t work: can I roll it back easily?”. If the answer is yes then you should be good to go :).
If you are working with Heroku
- Don’t ever clone from the heroku repo, clone from the github repo and maintain that as
origin, remember that we don’t use Heroku as version control, so make sure all your latest stuff is on github. There should never be a commit on heroku that was not in github first.
- CSS in the views is a no-no.
- Always use two-space indentation (soft tabs), make sure your editor does not insert tabs instead of spaces, as that might look different on different editors.
- Trailing spaces: I will murder you in your sleep.
- Don’t leave empty lines at the end of a file. It gives me micro-seizures.
- Never comment code and leave it there, we have git to remember our stuff, just delete it!
- Always indent properly.
There is a styleguide for ruby (made by the guys at github) linked below that is more or less consistent with the style we have at Cubox (and with the standards on the Ruby community in general). Please read it, it’s only about 5~10 minutes and definitely worth it. :)