xenon92/guidelines.md

## guidelines.md

      
    Raw
  

              guidelines.md
            
          
    Guidelines for Android Source Compilation

In this post, I'll share what "should" be done and
what "shouldn't" be done and the reason of this post.
If you want your ROM to succeed, you need to think about 2 types
of people.


Users - Every user cares about STABILITY. If your ROM doesn't stay stable, people will be quick to change their ROM to some other stable ROM.


Developers - If you want other developers to take notice of your ROM and contribute to it, you need to keep the source CLEAN. They care about the source code more.


What do I mean by CLEAN ?


Proper commit history.
No useless branches.

How to make proper commits?

Consider every commit as a piece of art. Every other person who knows about git history will be able to see your commit. The commits you make show how much you understand GIT and about these version control software like "git".
Give this link a read - torvalds/linux#17 (comment)
If you don't know who Linux Torvalds is, well, he is the developer of the software "git" itself. He is also the one who make the "linux kernel" and made it open source. Google more about him.
You 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.
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.
MOST IMPORTANT - Give a proper explanation of WHAT you changed and WHY you changed it and WHAT does the change do? Commit description should be so elaborating 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
IMPORTANT - Keep the one line commit header SHORT. Less than 50 character. Give longer explanation in commit summary.
IMPORTANT - Don't make lines longer than 80 characters in commit summary. Break lines into new lines.
DONT MERGE ANY COMMIT THAT CHANGES THOUSANDS OF FILES. IT IS IMPOSSIBLE TO TRACK WHAT HAS CHANGED.
Add few commits at a time, build and test your changes. Then add more. No point in adding 20-30 commits and then tracking down what went wrong.

Take a look at each and every commit in my Keep Trash repo - https://github.com/xenon92/xposed-keep-trash/commits/master
Take a look at how pawitp makes his commits. Take a look at commits in CM repos.
In android source, it is always a good habit to mention the repo you are making change to. example - you are making a commit to vendor/cm. Make your commit like this
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. Do it from command line. That is the proper way to do it.

Merge commits


Cherry-pick commits

cd path_to_repo_to_update_in_your_source

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 SHOULDN'T 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:
git status
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
CTRL+O ENTER then CTRL+X
Done.
Some useful commands

I don't know everything myself, and I learn new things everyday too. But we only learn when we start USING it.
git format-patch -1 commitid
git format-patch HEAD~7
The 2nd one 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
To amend the last commit you made.
git log
git rebase -i HEAD~<# of commits>
This is to squash commits into one commit.
Everyone learns from their mistakes. :)
###KEEP THE SOURCE CLEAN. YOU'LL LOVE MAKING COMMITS YOURSELF.