IMPORTANT NOTICE FOR ALL DEVELOPERS:
- Version 3 of Habitica's API was released on 21 May 2016.
- Version 2 was disabled on 30 July 2016. Any third-party tools still using version 2 stopped working after that date.
- Learn more at Application Programming Interface and the "API Changes" section in Guidance for Blacksmiths.
This page will help you use Git and GitHub after you have installed Habitica locally.
Fork and Clone Habitica Edit
Forking and cloning Habitica is an essential first step to setting up your local install. It needs to be done only once. The instructions for doing it are in the "Fork and Clone Habitica (All Operating Systems)" section in Setting up Habitica Locally.
Rebase Branch Edit
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 in GitHub
After updating, there may be new node packages in the project so run this again:
Rebase Problems Edit
While attempting to perform a rebase, many new and irrelevant commits appear in your branch. Don't panic! Here are some solutions to clean up the commit log:
Think of this as pruning the commit list. Open a
git log window and keep it open, displaying all the commit hash ID strings visible in a list.
git reset --hard HEAD~1 to remove one commit, or use HEAD~nb_of_commits if removing multiple commits.
To recover from accidentally deleting too many commits: use
git pull again from your fork, then copy the commit hash ID strings of the commits to re-add on top of your branch. The hash ID strings to retrieve are in the git log window left open before doing a reset.
git cherry-pick ee1768b7e2c0bcee9eff1a45be1e3543fac0687b
This command will re-add commit ee1768b7e2c0bcee9eff1a45be1e3543fac0687b on top of HEAD.
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"
Create a New Feature Edit
To start a new task, create a new branch for it. First, find which branch from which to start the feature. Do a
git branch -r to see the list of remote branches, and choose the appropriate branch depending on the task. This will almost always be the develop branch.
Github recommends creating branches locally on your computer to make collaboration with others easier.
For example: To start a task from the develop branch, do:
git checkout -b relevant_branch_name upstream/develop
Then once you've made changes, use
git push to push them to your fork in Github, and then do a Pull Request from there.
Assist Another user with a Feature Edit
To work on a feature already started by someone else and not yet merged in upstream, pull the other person's commits to your local install.
For example: The user 'jdoe' wrote a feature branch 'add_theme' which is awaiting a Pull Request into upstream/develop. You have your fork of upstream/develop, and would like to get jdoe's changes represented there right now, rather than waiting for jdoe's Pull Request to be approved.
git fetch upstream git checkout -b jdoe-add_theme upstream/develop git pull https://github.com/jdoe/habitrpg.git add_theme
Write Commits Edit
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 updates, if there are fewer changes in each commit.
For example: In a sequence of commits, there could be one commit dedicated to tests, followed by one with UI changes, and one (or more!) to write the logic. The admins can request updates and fixes to the UI commit without interrupting the review process for the logic or tests commits.
If changes are done over several days, make sure to rebase your branch to properly update your code. If some conflicts appear, it may be preferable to use the upstream version, using this command:
git rebase -Xours upstream/develop
Keeping your Commits Clean Edit
It is important commits only include files suitable for inclusion in Habitica's official repository. If any files are added for personal use, do not allow them to be included with a `git add` command.
Also do not specify the personal files in the repository's
.gitignore file, because changes to that file will be included in the official repository. Use your global
.gitignore file instead for excluding personal files from a commit.
Testing your Changes Edit
Before submitting your changes in a pull request, run all tests locally to see if any existing code is no longer working correctly. If it's uncertain why a test is failing, please ask for assistance in the issue comments. The problem may not be caused by your changes.
Running tests is not necessary before a pull request for partially completed work (e.g., when seeking assistance before finishing changes).
Pull Request Edit
When code is complete, partially complete, but feedback or assistance is needed before finishing, push your branch code into your fork with
Then go to https://github.com/YourUsername/habitrpg (replacing "YourUsername" with your Github username) and click on the Pull Request (PR) button.
Before saving the PR, follow these steps:
- Verify the merge will be done in the correct branch. Git often defaults to upstream/develop even if the branch was created from another branch. Although most requests will be made into the upstream/develop branch, be sure to check this and change it if necessary.
- Type a meaningful name for the PR that succinctly and accurately describes the change.
fixes #1234to the end of the name, where "1234" is the number of the issue being fixed. This step is not necessary if your PR is not fixing an existing issue.
- Describe your change in detail in the body of the PR. Please do not expect Habitica's staff and admins to understand the PR just by reading your code. The PR description gives the admins the context necessary to understand and approve code more rapidly.
- 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.
- Include your User ID string, found in Settings > API.
- 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.
- To ensure everything you write is seen by admins, it is best to always make new comments instead of editing old ones.
- If there is a reason to edit an existing comment, this can be done, but please also create a new comment containing the new or changed material.
- The new comment may be deleted after it's posted, since the only purpose the additional comment serves is to notify the admins with the new material.
- These same recommendations apply to Issues as well.
- Admins do not receive emails when new commits are added to an existing PR, so add a brief comment when you've pushed a new commit to trigger a notification to the admins.
PLEASE 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.