Woohoo, you've been given commit access to our repo! Here's what you should know:
- The purpose of this access is so that it's easier for you to work with ZPUI. You don't have to keep your fork up-to-date or anything and can easier pull new changes in the devel branch. Other developers (i.e. me) will also be able to join if you need help, and in general there's much less chance of your work being forgotten about even if it isn't finished. We'll also get IRC notifications for all of the commits!
devel
,staging
andmaster
branches are not available to you - they're our three main development branches that ZeroPhones can update from by default. If you want your code in one of these branches, I will want to review it through a pull request, just to make sure there's no breakage for users. Also, if someone steals your GH account, they might as well push malicious code into one of these branches, some users might update before we notice, then some of our users might permanently become part of a botnet - which is not a desirable situation ;-P- Thus, for features, bugfixes and other stuff that you did and want to see in the main branches, create your own branches and make PRs from that to devel. You might see the main developer (me) pushing straight to devel... I know this isn't fair, but I'll do my best to compensate for that - by reviewing and merging your PRs as soon as possible =)
- As usual, make your pull requests against
devel
, and make sure your branch is up-to-date withdevel
before making the PR. If your branch contains bugfixes that are also applicable for other branches, say so in the PR description and we'll merge it further. - When making a PR, go into the "Files changed" and "Commits" tabs, make sure there aren't any commits/changes you added by accident - if they're not desirable, I might ask you to remove these changes before merge.
- Please make PRs if you leave your branch for more than a couple of days and your code has a complete unit of work that we could already use. I.e. if the branch consists solely of a feature still in-progress, feel free to leave it as-is until you return to it. If your code has some TODOs implemented and they're fully-functioning but you want to continue work later, please consider making a PR either way - you can resume your work later when you get back to it. If it's both (let's say your branch has tests for an UI element that we could merge, but also contains some WIP code) - let us know, we can probably cherry-pick commits (an actual feature of git, you can read up on it in the workflow down below, step 12).
- If you need help with git, you can get it on our IRC/Matrix channels =) Here's a workflow that should get you through with all your work and then some:
git checkout branch_name
to switch to an existing branch (i.e.git checkout devel
to switch to ourdevel
branch)git checkout -b new_branch_name
to create a new branch (the branch created in this example will have "new_branch_name" for its name, so change as required). Next time you need to switch back to it, just usegit checkout new_branch_name
. Also, when you're creating a new branch, it matters which one you're currently on - say, if you're developing a new UI element in a separate branch, but then you notice some typos and want to send a quick PR, you might want togit checkout devel
before making that newfixing-typo
branch, otherwise the PR you'll send will contain your experimental commits as well, and that's not good.- Make your changes, test them in emulator / in unit tests / on real hardware
- Use
git status
to see all the files you've changed. It also has some usage tips, I'll add one - don't usegit checkout /path/to/file
unless you're fine with losing all changes you made to that file. Same forgit reset --hard /path/to/file
, I believe. - For adding your changes, avoid using
git add .
if you've changed files - a good rule is to avoid it in general (I never use it myself when working on ZPUI). Instead, do it like this:git add --patch /path/to/file
for each file which has changes you'd like to include in the commit. This will allow you to interactively review your changes and only commit the parts you want to be there for that commit. This way, there's less chances of unrelated changes and sensitive info (i.e. passwords) getting into your commit. (BTW, the interactive mode is pretty powerful, use ? to list all the options it provides.) - If you're added completely new files, you can't use
--patch
- just usegit add path/to/file
. Either way, don't usegit add .
. - Use
git diff
to see all of the changes you have in your tree, usegit diff --cached
to see changes you've alreadyadd
-ed but haven't yetcommit
-ed. - Use
git commit
to make a commit. If you've just made a commit and haven't pushed it yet, and now you realise you want to change the commit message, usegit commit --amend
. If you want to add some more changes to commit you've made and haven't pushed yet,add
those changes (with--patch
, preferrably), then usegit commit --amend
as well (edit the message if you want). - Use
git log
to see the list of all commits made in the branch you're currently in. To see changes made by a certain commit, usegit show c0mm1thash
. Thec0mm1thash
part is ~10 first characters of the long commit hash value, i.e.git show 0bc88ecae
if the commit you want to see is0bc88ecaef6efe85ab39043d64994504970824cf
(doesn't have to be 10 characters exactly, IIRC no less than 7 is a good rule). - If you want to bring your branch up-to-date with another branch - most likely,
devel
, - usegit merge devel
while being on the branch that you want to bring up-to-speed. If you have conflicts,git status
will give some good tips on resolving them - in general, in case of conflict, you'll need to edit files and see which parts you want to leave, which you want to merge manually and which you don't need anymore. - If you're not sure your local
devel
branch is up-to-date but you want to make sure your own branch is in sync, you can usegit pull origin devel
instead. - If you need to copy specific commits into your branch from another branch, use
git cherry-pick c0mm1thash
while being in the destination branch - again, get thec0mm1thash
usinggit log
in that branch.