As a developer, I have come across many source codes, developers and the way they maintain their code. Following are few best practices that a developer should follow for maintaining the source code of their app, software or android ROM. These practices are more concentrated on the source control management (SCM) software git and the android source code.
In the parallel universe of software development, there are three groups of people that interact.
Users - Everyone cares about stability. If the android ROM (or an app or a software) you compile isn't stable, users will be quick to switch to some other alternative that provides them with stability on a day-to-day basis.
Developers - If you want other developers to take notice of your developments and contribute to it, you need to keep the source clean. They care about the source code more.
Testers - They are developers' best friends. They test the development and provide feedback to developers to improve upon their source.
HOW TO MAKE PROPER COMMITS?
Consider every commit as a piece of art. The commits you make show your understanding of git and other version control software.
Give this conversation a read. Linux Torvalds is the developer of the software "git". He is also the creator of the "linux kernel".
Developers should follow a few guidelines to make proper commits.
- Don't be in a hurry to push commits online. Take your time on your local machine with your commit. Once it is pushed, there is nothing you can do about it (you can, but it increases an avoidable re-work).
- Avoid using Github's online commit maker. It is just a mess.
- Do not make 10 commits for the same feature/change you are trying to implement. Add all files you changed in one single commit or merge your commits before pushing them online.
- Give a proper explanation of what you changed, why you changed it and what does the change do? Commit description should be elaborating, so that the other person doesn't have to click on your commit to see what you did, but gets all the info from your commit summary.
- Keep the one line commit header short. It should be less than 50 character. Write the longer explanation in commit summary.
- Don't make lines longer than 80 characters in commit summary. Break long lines into new lines.
- Don't push any commit that changes thousands of files. It becomes almost impossible to track what has changed.
- Add few commits at a time, build and test your changes. Then add more. It makes no sense to add 20-30 commits and then tracking back what went wrong.
In android source, it is always a good habit to mention the repo in the commit. As an example, if you are making a commit to vendor/cm. This makes it easier to read in the list of hundreds of commits in gerrit.
git add -A git commit -m "vendor/cm: this is my change this is the commit summary broken into new lines because the lines were longer. You obviously dont have to count the number of characters, just get an idea of how to do it."
HOW TO UPDATE ANDROID SOURCE WITH UPSTREAM COMMITS?
Don't use pull requests. The proper way to do this is from command line.
- Merge commits.
- Cherry-pick commits.
Change directory to the repo source you want to update.
git remote add cm path_to_cm_repo_online git fetch cm git cherry-pick commitID1..commitiID2 OR git cherry-pick commitID
If you get merge conflict while merging/cherry-picking, don't ignore it. Abort the merge/cherry-pick with command on your terminal.
- Rebase the commit you match your source manually.
- Then, merge again.
There should not be a commit that says "Fix merge conflicts" - where you remove >>>>>HEAD, etc.
If in middle of cherry-pick or merge, error comes, do the following:
That will show you which files have been successfully changed and which ones are not by red color. Then open those red files and fix them manually. After you are finished:
git add -A git commit
Then nano will open in command line
Press CTRL+O ENTER then CTRL+X
SOME USEFUL COMMANDS
I do not consider myself as a git virtuoso, but these commands come in handy and increase the overall productivity.
git format-patch -1 commitid git format-patch HEAD~7
The second commande creates patch files for all the previous 7 commits from your HEAD (last) commit.
git reset --hard HEAD~1
This removes your current commit and rolls back to the previous commit
git commit --amend
This is to amend the last commit you made.
git log git rebase -i HEAD~<# of commits>
This is to squash multiple commits into one commit.
KEEP THE SOURCE CODE CLEAN.