User:Lexinatrix/Sandbox/Using Habitica Git

If you haven't already, please see the Guidance for Blacksmiths main page first. Be sure to also read  Setting up Habitica Locally  for important information about getting started.

 The following brief tutorial explains how to perform the following actions on Git:
 * Fork and clone the habitrpg repository
 * Create new feature branches
 * Perform Pull Requests

(Use this image for header:  http://habitica.wikia.com/wiki/File:Coding_3_by_phoneix_faerie-d7idtti.png )

Fork and Clone Habitica
The easiest way to fork Habitica is to go to the habitrpg github page and click the Fork button. After that, do a git clone of your own repository.

Another way to accomplish this is to use this command: git clone https://github.com/HabitRPG/habitrpg.git 

Then use the following command, replacing "YourUsername" in the command with your github.com username. cd habitrpg git remote set-url origin https://github.com/YourUsername/habitrpg.git 

Finally, use this command: git push to update your fork.

Setup Upstream Remote
Next step is to keep track of the upstream habitrpg repository, so we can easily update our fork with the latest changes. Because origin is the url to our fork, we will create another remote upstream for habitrpg: git remote add upstream https://github.com/HabitRPG/habitrpg.git Then, every time you want to get habitrpg's latest code, you can do: git fetch upstream

Rebase Branch
When you want to update your local branch, you need to rebase it from the upstream branch. Let's update develop: git checkout develop git fetch upstream git rebase upstream/develop git push # to update your fork If you get the error "fatal: 'upstream' does not appear to be a git repository", then follow the instructions in the Setup Upstream Remote section above.

After updating, there may be new node packages in the project so run this again: sudo npm install

Create a New Feature
To start a new task, create a new Pull Request for it. First, you need to find which branch from which to start the feature. Do a git branch -r to see the list of remote branches. Choose the appropriate branch depending on the task you want to work on. This will almost always be the develop branch.

<p data-parsoid="{"dsr":[10754,10855,0,0]}">For example: You decide to start your task from the develop branch. To create your feature, do: git checkout -b relevant_branch_name upstream/develop <p data-parsoid="{"dsr":[10916,11047,0,0]}">Then you can make your changes, use git push to push it to your fork in Github, and then do a Pull Request from there.

Assist Another user with a Feature
<p data-parsoid="{"dsr":[11090,11224,0,0]}">To work on a feature already started by someone else and not yet merged in upstream, you can pull their commits to your local install.

<p data-parsoid="{"dsr":[11226,11438,0,0]}">For example: The user 'jdoe' wrote a feature branch 'add_theme' which is awaiting a pull request into upstream/develop. You also have your fork of upstream/develop, and would like to get jdoe's changes right now. git fetch upstream git checkout -b jdoe-add_theme upstream/develop git pull https://github.com/jdoe/habitrpg.git add_theme

Write Commits
<p data-parsoid="{"dsr":[11595,11812,0,0]}">Doing regular small commits of code is recommended rather than large commits, because they are easier for the admins to review. It's also easier for developers to refuse or edit one specific commit that needs changes.

<p data-parsoid="{"dsr":[11814,11942,0,0]}">For example: There could be a commit dedicated to tests, followed by one with UI changes, and one (or more!) to write the logic.

<p data-parsoid="{"dsr":[11944,12163,0,0]}">If your changes are done over several days, make sure you rebase your branch to properly update your code. If some conflicts appear, you might want to use the upstream version: git rebase -Xours upstream/develop

Keeping your Commits Clean
<p data-parsoid="{"dsr":[12240,12689,0,0]}">It is important the commits you make include only files that are suitable for inclusion in Habitica's official repository. If you add any files purely for your own use, do not allow them to be included with a `git add` command. Also do not specify them in the repository's .gitignore file, because changes to that file will be included in the official repository. You can use your global .gitignore file for personal files.

Testing your Changes
<p data-parsoid="{"dsr":[12718,13022,0,0]}">Before submitting your changes in a pull request, run all tests locally to see if anything is no longer working correctly. If you're uncertain why a test is failing, please ask for assistance in the issue comments, because the problem may not be caused by your changes.

<p data-parsoid="{"dsr":[13024,13174,0,0]}">Running tests is not necessary before a pull request for partially completed work (e.g., if you are seeking assistance before finishing your changes).

Pull Request
<p data-parsoid="{"dsr":[13194,13349,0,0]}">When you've finished your code, or half-finished it but would like feedback or assistance, push your branch code into your fork with git push.

<p data-parsoid="{"dsr":[13351,13509,0,0]}">Then go to https://github.com/YourUsername/habitrpg (replacing "YourUsername" with your Github username) and click on the Pull Request (PR) button.

<p data-parsoid="{"dsr":[13511,13538,0,0]}">Before saving the PR:
 * 1) Verify the merge will be done in the correct branch. Git often defaults to upstream/develop even if you created your branch from another one. Although most requests will be made into the upstream/develop branch, be sure to change this if necessary for your changes.
 * 2) Type a meaningful name for the PR that succinctly and accurately describes the change.
 * 3) Add fixes #1234 at the end of the name, where "1234" is the number of the issue that is being fixed. This step is not necessary if your PR is not fixing an issue.
 * 4) Describe your change in detail in the body of the PR. Please do not expect Habitica's staff and admins to work out what your PR does by just reading your code. The PR description gives the admins the context necessary to understand and approve your code more rapidly.
 * 5) If your PR changes any user-visible parts of Habitica, include screenshots showing both the existing behavior and the new behavior to help demonstrate what is changing.
 * 6) Include your User ID string (found in Settings > API).
 * 7) Admins will receive emails for all new PRs and all new comments added to PRs, but they are not emailed when any comment in the PR is edited.
 * 8) *To ensure everything you write is seen by admins, it is best to always make new comments instead of editing old ones.
 * 9) *If there is a reason to edit an existing comment, you're welcome to do so but please also create a new comment containing the new or changed material.
 * 10) *You may delete the new comment after you've made it if you wish, since the only purpose it serves is to get the new material into the email notifications.
 * 11) *These same recommendations apply to Issues as well.
 * 12) Admins also don't receive emails when new commits are added to an existing PR, so add a brief comment when you've pushed a new commit.

Problems
<p data-parsoid="{"dsr":[15407,15564,0,0]}">While attempting to perform a rebase, there are many new and irrelevant commits in your branch. Don't panic! Here are some solutions to get out of that mess:

Cherry-pick
<p data-parsoid="{"dsr":[15586,15740,0,0]}">Think of this as pruning your commits. Open a git log window, and keep it open, displaying all your commit hash ID strings visible in a list.

<p data-parsoid="{"dsr":[15742,16186,0,0]}">You can now perform a git reset --hard HEAD~1 to remove one commit, otherwise use HEAD~nb_of_commits if you have more than one commit to remove. If you accidentally delete too many commits, just git pull again from your fork. Then copy the commit hash ID strings of the commits you want to re-add on top of your branch. You can retrieve the hash ID stringes from the git log window you left open before doing a reset.

<p data-parsoid="{"dsr":[16188,16200,0,0]}">For example: git cherry-pick ee1768b7e2c0bcee9eff1a45be1e3543fac0687b <p data-parsoid="{"dsr":[16263,16343,0,0]}">This will re-add commit ee1768b7e2c0bcee9eff1a45be1e3543fac0687b on top of HEAD.

Stash
<p data-parsoid="{"dsr":[16359,16597,0,0]}">If working together with others on the same branch, and pushing on the same remote, the push attempt may fail. If the push attempt failed because remote has a different HEAD than your local repository, don't pull! Instead, do this: git reset --soft HEAD~n_local_commits_ahead git stash git pull git stash pop git commit -am "message"

Do not work with habitrpg-shared
<p data-parsoid="{"dsr":[16761,17274,0,0]}">NOTE!  habitrpg-shared has been deprecated. If you see any instructions telling you to take actions in habitrpg-shared, please report them in the Aspiring Coders guild and ask for clarification if you need it. The habitrpg-shared files have been moved to the /common subdirectory under habitrpg, and all actions you used to do in habitrpg-shared can be done there.