Using Your Local Install to Modify Habitica's Website and API

To contribute code to Habitica's habitica.com website and API, first follow the instructions in Setting up Habitica Locally. Once your local install is working, this page will give you information about how to proceed with making a change. You can refer back to this page each time you start a new change or when you run into trouble with your local install.

This page is not relevant for contributing to development for the mobile apps.

General Notes

 * You must also read Guidance for Blacksmiths.
 * Join the Aspiring Blacksmiths guild and read it every day while you are working on code for Habitica. Important announcements are made there. For example:
 * When Habitica's dependencies are updated, a post will advise you to run  (see "Updating Your Local Install" below for the full process).
 * When new environment variables are added to Habitica's server, a post will advise you to update your copy of  by comparing it to
 * If you experience an error at any point in any of the instructions on this page, resolve that error before going further. Ask for help in the Aspiring Blacksmiths guild if necessary.
 * Some familiarity with `git` and GitHub is assumed here. Guidance for Blacksmiths contains links to generic documentation and links to relevant sections are presented below so that you can learn about any git commands that you don't understand.
 * If your local install was made before October 2016, delete it and go through the full installation process described in Setting up Habitica Locally.
 * If anything in this page seems incorrect or confusing, ask in Aspiring Blacksmiths. If you're certain something is incorrect, you're welcome to edit this page!

Updating Your Local Install
If a day or more has passed since you created or updated your local install, before starting work on any change follow these steps to ensure your install is up to date. Also follow these steps if you ever experience any problems with your local install before asking for help, or if you've been working on a change for several days and you think your local install might not have the latest code.


 * 1) If you have uncommitted changes, commit them or stash them.
 * 2) Checkout the   branch and rebase it:
 * 3) Compare your local config.json file with the config.json.example file and if there are any changes, apply them to config.json:
 * 1) Compare your local config.json file with the config.json.example file and if there are any changes, apply them to config.json:
 * 1) Compare your local config.json file with the config.json.example file and if there are any changes, apply them to config.json:
 * 1) Compare your local config.json file with the config.json.example file and if there are any changes, apply them to config.json:

It is permitted to have differences between the two files (for example, you might need to use a different port number than the default one) but you must always fully understand the reasons for the differences and document them in your own notes for your own future reference. If you are not sure why your config.json file is different, overwrite it with. Tip:  (note the hyphen) will switch between your current branch and the previous one you were using.
 * 1) Update any node packages by running  . Carefully review the output for errors and resolve the errors before continuing.
 * 2) Run   and briefly test that the http://localhost:3000/ website works.
 * 3) If you already have a branch that you have been using to make changes:
 * 4) Checkout the branch:
 * 1) Use git diff to examine the differences between your branch and the   branch:

If there are differences that are not from changes you have made to your branch, decide whether you should bring those changes into your branch now or later. If you are not sure, do it now. To apply differences:
 * 1) Fix any merge conflicts that might exist.
 * 2) Reapply changes that you stashed, if any.
 * 1) Reapply changes that you stashed, if any.

Creating a Change
When you're ready to start making a change to Habitica's website or API, follow this process:


 * 1) If you have not yet decided what change to make, refer to "Ways to Help" &gt; "Website" in Guidance for Blacksmiths.
 * 2) If you're not certain that it's okay to proceed with the change, ask in the appropriate GitHub issue or Trello card and wait for an admin to comment. For Trello cards, you should always ask because many feature requests are not approved for implementation. If an admin doesn't reply after three days, post again in the same place. All admins receive emails for all comments in GitHub and some receive emails for all Trello comments.
 * 3) Create a new branch in your local install for this change. Do not do any development in the   branch (it will cause problems for you as soon as you want to work on more than one change at once). To create a new branch:
 * 4) Start coding!
 * 5) When you have progressed far enough that you want to make a commit, give it a meaningful name that describes the code changes being made in that specific commit. This will help admins and other developers review your work. Make as many commits as you feel necessary - you do not need to limit yourself to one commit per change.
 * 6) * Remember that if you are adding new files to the repository, you will have to use git add on those files before you commit them.
 * 7) If you want to move to a different branch before you are ready to commit (e.g., to test unmodified code in the   branch), you can stash your changes.
 * 1) * Remember that if you are adding new files to the repository, you will have to use git add on those files before you commit them.
 * 2) If you want to move to a different branch before you are ready to commit (e.g., to test unmodified code in the   branch), you can stash your changes.

Testing your Change Manually
Before submitting your code for review, log in to the website in your local install and test your feature or bug fix thoroughly.


 * Refer to the "Run Habitica" section in Setting up Habitica Locally for how to get the website working locally.
 * If you need to make code changes after starting the local site, refer to "Restarting the Local Web Server" below.
 * Test all aspects of your new code in the website (and/or by using direct API commands if you have modified the API).
 * Also test any existing features that are related to the code you've changed to ensure that they are still working as intended. For example, if you are modifying the task editing screen, you might want to check that editing challenge tasks and group plan tasks has not been affected inappropriately.
 * In the footer of your local install's website, there is a debug menu with several useful tools for quickly modifying a test account (e.g., giving all mounts to the account). This can make testing your code faster and more efficient. Experiment with the menu items to find out what each one does.

Restarting the Local Web Server
The commands listed in the "Run Habitica" section in Setting up Habitica Locally will start a web server that uses the current code in your local install. When you change that code, you can make the local website use the new code by manually stopping the processes with Ctrl-C and restarting them as described in that section.

However to make restarting more convenient, the local Habitica web server uses nodemon. It watches the source code in your local copy of the repository and automatically restarts the web server when the code changes. This means that you usually don't need to do Ctrl-C and a restart.

You can also force nodemon to restart the web server by typing  and then hitting   in the same terminal that   is already running in. As a reminder of that, if you examine the output of ), you'll see this explanation: Running "nodemon:dev" (nodemon) task [nodemon] v1.2.1 [nodemon] to restart at any time, enter `rs` [nodemon] watching: *.* [nodemon] starting `node ./website/src/server.js`

However if you find that the local website does not seem to be using your latest code changes, it is advisable to use Ctrl-C and restart the processes.

Creating and Running Automated Tests
Habitica has a test suite in the top-level test directory. When Habitica's admins deploy a new version of the website to production, the deployment process runs the tests and refuses to deploy the site if there are any failed tests.

Before you submit your code for review, ideally you should ensure that all existing tests pass. You should also create new tests for every aspect of your feature or bug fix and ensure your tests pass.

However sometimes it is not possible to run the full test suite locally because the tests time out or fail for reasons unrelated to your code. If you are unable to run the existing tests or unsure which new tests you should create, you can submit the code you've written so far for review in a pull request (as described in a section below) and ask for advice about tests.

When you create a pull request, the full test suite is run by Travis CI. If any tests fail, Travis will report the results in your pull request and give a link to the test output. This is a good alternative for testing your code if running the full test suite times out locally. Sometimes even the Travis build times out or reports errors due to temporary problems, in which case admins can restart it to rerun all the tests.

If any failed tests are caused by your code, you will need to modify your code before your pull request can be merged.

To run the full test suite locally:
 * 1) Ensure that the MongoDB database server is running.
 * 2) Stop any npm process such as   or any process that is already running tests (don't try to run two test processes at the same time).
 * 3) Run  . This step is not always necessary, but if you have recently run tests and try to run them again, you might see errors such as   and   Killing all node processes will prevent those errors.
 * 4) Change directory into the top-level directory of your local install.
 * 5) Run the entire test suite locally by using   and fix any errors that are reported.
 * 6) If you suspect that errors might not be caused by your code, investigate that by testing in the   branch:
 * 7) Commit or stash your changes.
 * 8) Move back to your own branch with
 * 9) Create new tests for all parts of your new or modified code and ensure that they all pass.
 * 1) Move back to your own branch with
 * 2) Create new tests for all parts of your new or modified code and ensure that they all pass.

Running a Subset of the Automated Tests
While you are editing code or creating tests, it is often convenient to run only those tests that are relevant to your changes. This section gives you tips for doing that.

The full  command is equivalent to   which will run, in order: If one of those fails, the whole  command blocks and fails. You can run each of those commands by itself if you are interested in only one type of test.
 * (lint tests, which help to ensure code quality and consistency)
 * (unit tests)
 * (integration tests)

Alternatively, you can run even fewer tests at once:
 * To run only a single test, change  to
 * To run only one section of tests, change  to
 * can be added to more than one test or section to run all of those tests / sections but no others.
 * Remember to always remove  before committing your changes!


 * To run all tests from a single file:
 * Run  in one terminal session.
 * Wait for it to get to  and then leave it running.
 * In another terminal session, run:


 * To run all tests in one subdirectory:
 * Run  in one terminal session.
 * Wait for it to get to  and then leave it running.
 * In another terminal session, run:

Integration Tests
The integration tests are for testing Habitica's API. They are performed by making HTTP requests to the API's endpoints and asserting on the data that is returned.

Each top level API route has its own integration test directory. For example, all the routes that begin with /groups/ are in /test/api/v3/integration/groups/.

Each file in an integration test directory should encompass a single route and follow this file naming standard: For example, for the POST route https://habitica.com/api/v3/groups/:groupId/leave, the tests are in the file test/api/v3/integration/groups/POST-groups_groupId_leave.js
 * begin with the REST parameter for the route (POST, GET, etc)
 * display the full name of the route with  replaced by
 * end with

If you need to fix errors reported by the integration tests, you might find it helps to run the web server at the same time as the tests so that you can inspect the web server's output caused by the tests. To do that, in one terminal run:

and then in a different terminal window run:

Promises in Integration Tests
To mitigate callback hell, there is a helper method to generate a user object that can make HTTP requests that return promises. This makes it easy to chain together commands. All you need to do to make a subsequent request is return another promise and then call  on the surrounding block, like so:

it('does something', => {  let user;

return generateUser.then((_user) => { // We return the initial promise so this test can be run asyncronously   user = _user;

return user.post('/groups', {     type: 'party',    }); }).then((party) => { // the result of the promise above is the argument of the function return user.put(`/groups/${party._id}`, {     name: 'My party',    }); }).then((result) => { return user.get('/groups/party'); }).then((party) => { expect(party.name).to.eql('My party'); }); });

If the test is simple, you can use the chai-as-promised  syntax to make your assertion.

it('makes the party creator the leader automatically', => {  return expect(user.post('/groups', {    type: 'party',  })).to.eventually.have.deep.property('leader._id', user._id); });

If the test is checking that the request returns an error, use the `.eventually.be.rejected.and.eql` syntax.

it('returns an error', => {  return expect(user.get('/groups/id-of-a-party-that-user-does-not-belong-to'))    .to.eventually.be.rejected.and.eql({ code: 404, text: t('messageGroupNotFound'), }); });

Running Tests in Vagrant
If you are running the tests in vagrant, you might see the following error:

Error: /vagrant/.eslintrc: Configuration for rule "func-style" is invalid: Value "2,declaration,[object Object]" has more items than allowed.

or many instances of these:

1:1 error  Definition for rule 'no-empty-pattern' was not found    no-empty-pattern 1:1 error  Definition for rule 'no-arrow-condition' was not found  no-arrow-condition

You might also find that this test starts but never completes: Starting 'test:e2e:safe'...

You can avoid those problems by editing two files in the top-level directory of your local install.


 * Edit  to comment out these lines:


 * Edit  to comment out this line:

Do not commit those changes because those lines are needed for running tests on the server.

Tips
Code formatting and quality: Maintain the coding standards that are already in use in the code base (e.g., two spaces for each indentation level). We use lint to ensure consistent code formatting. When submitting a pull request, an automatic test suite will run over your code and will fail if lint indicates problems. The tests must pass before your code can be accepted.

Gender-neutral language: When writing documentation or code comments, use gender-neutral language (e.g., don't use "he" or "she" or "he/she"). We typically use they / them as a singular pronoun throughout Habitica to cover people of all genders.

Keep your commits clean: Commits must contain only files suitable for inclusion in Habitica's official repository. If you add any files for personal use, never specify them in a git add or  command. Also do not specify them in the repository's  file because changes to that file will be included in the official repository; use your global   file instead.

API documentation changes: If you will be modifying the API documentation, you will want to access the local copy. Run  to compile them once and view them at http://localhost:3000/apidoc/ (replace 3000 with the appropriate number if your local install uses a different port). Use  to allow the documentation to be automatically recompiled every time you save a change to the API's files.

Submitting your Change for Review in a Pull Request
When you have finished your change, create a Pull Request (PR) using the process below. You can also do this if you need help with your code or tests, as this is the best way to show your code to Habitica's admins.


 * 1) Commit any uncommitted changes (use a meaningful commit message).
 * 2) If significant time has passed since you created the branch, rebase your branch to merge in the latest changes from  :
 * 3) Fix any merge conflicts.
 * 4) Re-test your changes manually, especially if the rebase modified any code related to them.
 * 5) Re-run
 * 6) Fix any problems and commit again.
 * 7) If you are making a PR for a work in progress (WIP) to seek help with your code, it is not necessary for the tests to pass.
 * 8) Push your commits to your fork of Habitica in GitHub:
 * 1) If you are making a PR for a work in progress (WIP) to seek help with your code, it is not necessary for the tests to pass.
 * 2) Push your commits to your fork of Habitica in GitHub:


 * 1) In GitHub, create a pull request (PR) (in brief, go to  https://github.com/YourUsername/habitica  and click on the "Pull Request" button).
 * 2) * Give your PR a meaningful title that describes the bug being fixed or the feature being created / modified.
 * 3) * If your PR will fully fix an issue, add "fixes [URL of issue]" to the end of the title.
 * 4) * If your PR will partially fix an issue, add "partial fix for [URL of issue]" to the end of the title.
 * 5) * If you are making a PR to seek help with your code, put "WIP" at the start of the title,
 * 6) * Follow the instructions that you'll see in the comment field of the PR.
 * 7) * Always write a meaningful explanation of your change in detail in the body of the PR. Don't rely on the title explaining it fully and please don't expect the 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, and also allows non-technical staff and contributors to determine if your PR is relevant to them.
 * 8) * If your change has a visible effect on the website, include screenshots showing the existing and new behavior to help demonstrate what is changing. To learn how to add images, see the note at the bottom of GitHub's comment field.
 * 9) * If your change implements an idea in Trello, include a link to the Trello card. If the card contains multiple ideas, explain which one you are implementing.
 * 10) * If you are making a PR to seek help with your code, include the above information and also state that the PR is not complete and describe the help you need.
 * 11) Admins will receive an email when your pull request is created so you do not need to inform them in any way. If your pull request references an issue, the issue will be updated automatically to contain a link to your PR.

Having your Pull Request Tested and Reviewed
When you make a PR, Habitica's automated tests will be run by Travis CI. Two test builds are run, one against your branch and one against your branch as if it had been merged into the most recent  branch in Habitica's repository. These tests will fail if there are problems with your code and you can use the links that Travis CI provides to review the failures. However there should normally be no failures if you had run  successfully in your local install. Sometimes the tests will fail from problems that aren't related to your change (e.g., if timeouts happen during the test build); if so, admins will restart the test build and you will not need to take any actions. However you should always review test failures to work out if they are from your code or not. If failures are from your code, admins will ask you to fix the problems before they test and review your code.

After the test build succeeds, one or more admins will review your pull request by testing it on their own local install and reading your code changes. Admins will try to do this promptly but the timeframe depends to some extent on how many PRs there are and other factors. PRs for bug fixes will usually be reviewed first because those are highest priority. Other PRs will usually be reviewed in the order that they were received, though sometimes a high priority PR might skip ahead.

Admins might request changes and will then apply the GitHub label to your pull request. When that happens, before your pull request can be accepted, you will need to make those changes or explain why you think they should not be made. Admins can be identified by GitHub's "Member" indicator to the right of their names; any person in GitHub who does not have that indicator is not an admin, even if they seem to be speaking with authority.

Other contributors might also suggest changes. Implementing them might be optional, depending on the suggestion, but experienced contributors often make good suggestions. If you notice that an admin has commented favourably on a contributor's suggestion or has given it a positive emoji (e.g., thumbs up or a smiley face) then it's recommended that you do implement the suggestion or explain why you think it should not be implemented.

If you don't understand the changes requested or are having trouble with them, don't be afraid to ask for help! You are also welcome to commit and push partial changes if you need advice about how to finish them.

If other PRs are merged to  while yours is being reviewed, admins might ask you to fix merge conflicts. This can be done in your local install by merging in the latest version of  and manually editing the conflicts that git tells you about. You are welcome to ask for advice about this if needed!

When you have handled all feedback given to you by admins (and optionally by contributors), add a comment to the PR to state that the PR is ready for review again. Admins will then replace the label with the the  GitHub label and your PR will go back into the queue for further review.

If your PR has the label and you haven't made any updates or comments for a month, admins will ask you about your progress. You will have a week to respond to confirm that you’re still working on the PR or your claim on the PR and any associated issue will lapse. You’ll be able to refresh a claim three times before it will lapse automatically. Once your claim has lapsed, admins will either take over the PR to complete it themselves or will release it to the developer community for someone else to work on. If you completed some work that is later merged, you’ll receive partial contributor credit. Admins might shorten these turnaround times if the PR is of high priority - they will clearly state a due date in those cases.

Some of this information was initially released by SabreCat in the PR Process Update blog post.

Making Changes to your PR
To change or rebase code that has already been submitted in a PR:
 * 1) In your local install, go to the branch that you created for your change:


 * 1) Make the code changes or do the rebase and fix any merge conflicts.
 * 2) Commit the changes, using a meaningful commit message (e.g., describe the fixes that were made in response to feedback). If you are just rebasing you might find that no new commit is needed.
 * 3) Push your to your fork of Habitica in GitHub using the same command you used for the original push:

That will automatically update your PR.
 * 1) * If you have rebased since the last time you pushed, you might find that a normal push command fails and that you need to do a forced push by specifying :


 * 1) * Note that as a general rule you should be cautious about using  to force any git command to succeed. It's expected and generally necessary when pushing after a rebase, however in any other situation make sure that you understand the consequences of using   before you use it.
 * 2) When you have finished making changes and pushing, add a comment to the PR to say what has changed and to state that it is ready for review again.

Note that admins will receive emails for all new comments added to PRs, but they are not emailed when any existing comment is edited so to ensure everything you write is seen by admins, make new comments instead of editing old ones. If there is a reason to edit an old comment, you can do that but please also create a new comment to explain what has changed in the previous comment.

Reviewing Other Contributors PRs
Habitica welcomes members of the coding community to review each others’ work and add comments or suggestions on PRs. However please only review if you have a good understanding of the code and have experience with the functional area covered by the PR.

Habitica's staff are considering the possibility of having a new contributor title for users who are doing a particularly good job with reviewing and testing PRs. More information will be given later if this proceeds.

This information was initially released by SabreCat in the PR Process Update blog post.

Acceptance of Your PR
When an admin decides that your pull request is ready to be accepted, they will merge it into develop and will comment on the PR to state that either you have been given a contributor tier or that your PR has been noted as credit towards your next tier.

Occasionally admins forget to update your Habitica account with information about your PR (and are always sorry about that!) If your PR is merged and a day later there is still no comment in it from an admin regarding a new tier or credit towards a tier, please post to the PR to ask about it. Similarly, if an admin has stated that you have been given a new tier but you have not seen your tier increase in Habitica, please ask in the PR. Admins really do want to know when they have forgotten this important step! If you believe that this might have happened in any old PRs that you or others might have made, you are welcome to ask in those are PRs, no matter how old they are.

After merging, your change will remain in a staging area for up to two weeks for additional testing before it appears in Habitica's production website (see the "Release Cycle" section below for details). When appropriate, admins will migrate all changes in staging to the production website. You can monitor the Releases page to find out when this happens. There can be a delay of a couple of hours between the Releases page being updated and the new release appearing on the Habitica website.

Release Cycle
Habitica's admins use a fixed two-week release cycle for PRs from contributors and for most of their own PRs. You do not need to take any actions related to this and this section is purely for your own interest.

The purpose of the release cycle is to allow each merged PR to remain on a staging website for up to two weeks for additional testing by admins and staff.

When a PR has been reviewed, tested, and determined ready for release, admins take different actions depending on whether the current week's number is odd or even, using Week Numbers for 2017:
 * Odd weeks: The PR is immediately merged to the  branch, which releases it into a staging website.
 * Even weeks: The PR is marked with the label "status: pr: tested and approved; merge pending" and is not merged.

At the end of an even week, admins will:
 * 1) Deploy the staging site to production, meaning that all PRs merged over the previous two weeks are now live.
 * 2) Update the Releases page with a list of the changes that have just gone live.
 * 3) Merge to   any PRs labelled with "status: pr: tested and approved; merge pending". Those PRs now stay in staging until the end of the next even week.

Admins and staff use the staging site for as much of their normal use of Habitica as possible. This means that new features and bug fixes are used under real-world conditions by several people for at least one week before becoming available to all Habiticans. This helps admins notice any errors that might have been missed during testing (e.g., if other PRs have negative interactions with your PR). The staging area is not available to other Habiticans.