To contribute code to Habitica's 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 NotesEdit

  • 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 npm install (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 config.json by comparing it to config.json.example
  • 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 InstallEdit

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 develop branch and rebase it:
    1. git checkout develop
    2. git fetch upstream
    3. git rebase upstream/develop
  3. Compare your local config.json file with the config.json.example file and if there are any changes, apply them to config.json:
    diff config.json.example config.json
    cp config.json.example 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 config.json.example.
  4. Update any node packages by running npm install. Carefully review the output for errors and resolve the errors before continuing.
  5. Run npm start and briefly test that the http://localhost:3000/ website works.
  6. If you already have a branch that you have been using to make changes:
    1. Checkout the branch: git checkout name-of-your-branch
      Tip: git checkout - (note the hyphen) will switch between your current branch and the previous one you were using.
    2. Use git diff to examine the differences between your branch and the develop branch:
      git diff upstream/develop
      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. git rebase upstream/develop
      2. Fix any merge conflicts that might exist.
      3. Reapply changes that you stashed, if any.

Creating a ChangeEdit

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" > "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 develop 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:
    1. git fetch upstream
    2. git checkout -b name-of-your-branch upstream/develop
  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.
    • 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.
  6. If you want to move to a different branch before you are ready to commit (e.g., to test unmodified code in the develop branch), you can stash your changes.

Testing your Change ManuallyEdit

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

Debug Menu
  • Run npm start and visit your localhost website in your browser (refer to the "Run Habitica" section in Setting up Habitica Locally for details).
  • If you need to make code changes after running npm start, 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 ServerEdit

The npm start command starts 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 web server with Ctrl-C and restarting it by running npm start again.

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 npm start.

You can also force nodemon to restart the web server by typing rs and then hitting Enter in the same terminal that npm start is already running in. As a reminder of that, if you examine the output of npm start), 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 rerun npm start.

Creating and Running Automated TestsEdit

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 npm start or any process that is already running tests (don't try to run two test processes at the same time).
  3. Run killall node. 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 "before all" hook: callee$2$0 and Error: connect ECONNREFUSED. 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 npm test 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 develop branch:
    1. Commit or stash your changes.
    2. git checkout develop
    3. npm test
    4. Move back to your own branch with git checkout -
  7. Create new tests for all parts of your new or modified code and ensure that they all pass.

Running a Subset of the Automated TestsEdit

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 npm test command is equivalent to gulp test:api-v3 which will run, in order:

  • gulp lint (lint tests, which help to ensure code quality and consistency)
  • gulp test:api-v3:unit (unit tests)
  • gulp test:api-v3:integration (integration tests)

If one of those fails, the whole npm test command blocks and fails. You can run each of those commands by itself if you are interested in only one type of test.

Alternatively, you can run even fewer tests at once:

  • To run only a single test, change it('test name', ...) to it.only('test name', ...)
  • To run only one section of tests, change describe('section name', ...) to describe.only('section name', ...)
  • .only can be added to more than one test or section to run all of those tests / sections but no others.
  • Remember to always remove .only before committing your changes!
  • To run all tests from a single file:
    1. Run gulp test:nodemon in one terminal session.
    2. Wait for it to get to info: Connected with Mongoose and then leave it running.
    3. In another terminal session, run:
      mocha test/<subdirectory>/<filename.js> --require ./test/helpers/start-server
  • To run all tests in one subdirectory:
    1. Run gulp test:nodemon in one terminal session.
    2. Wait for it to get to info: Connected with Mongoose and then leave it running.
    3. In another terminal session, run:
      mocha test/<subdirectory> --recursive --require ./test/helpers/start-server

Integration TestsEdit

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:

  • begin with the REST parameter for the route (POST, GET, etc)
  • display the full name of the route with / replaced by _
  • end with .test.js

For example, for the POST route, the tests are in the file test/api/v3/integration/groups/POST-groups_groupId_leave.js

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:
NODE_ENV=test npm start
and then in a different terminal window run:
gulp test:api-v3:integration:separate-server

Promises in Integration TestsEdit

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 .then((result) => {}) 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'/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('My party');

If the test is simple, you can use the chai-as-promised return expect(somePromise).to.eventually syntax to make your assertion.

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

If the test is checking that the request returns an error, use the `` syntax.

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

Running Tests in VagrantEdit

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 .eslintrc to comment out these lines:
    • "no-empty-pattern": 2,
    • "no-arrow-condition": 2,
    • "func-style": [2, "declaration", { "allowArrowFunctions": true }],
  • Edit tasks/gulp-tests.js to comment out this line:
    • 'test:e2e:safe',

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


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 git commit command. Also do not specify them in the repository's .gitignore file because changes to that file will be included in the official repository; use your global .gitignore file instead.

API documentation changes: If you will be modifying the API documentation, you will want to access the local copy. Run gulp apidoc 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 gulp apidoc:watch 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 RequestEdit

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 develop:
    1. git fetch upstream
    2. git rebase upstream/develop
    3. Fix any merge conflicts.
    4. Re-test your changes manually, especially if the rebase modified any code related to them.
    5. Re-run npm test
    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.
  3. Push your commits to your fork of Habitica in GitHub:
    git push origin name-of-your-branch
  4. In GitHub, create a pull request (PR) (in brief, go to and click on the "Pull Request" button).
    • Give your PR a meaningful title that describes the bug being fixed or the feature being created / modified.
    • If your PR will fully fix an issue, add "fixes [URL of issue]" to the end of the title.
    • If your PR will partially fix an issue, add "partial fix for [URL of issue]" to the end of the title.
    • If you are making a PR to seek help with your code, put "WIP" at the start of the title,
    • Follow the instructions that you'll see in the comment field of the PR.
    • 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.
    • 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.
    • 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.
    • 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.
  5. 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 ReviewedEdit

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 develop 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 npm test 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 status: pr: with author: needs work 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 develop 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 upstream/develop 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 status: pr: with author: needs work label with the the status: pr: ready for review GitHub label and your PR will go back into the queue for further review.

If your PR has the status: pr: with author: needs work 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 PREdit

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:
    git checkout name-of-your-branch
  2. Make the code changes or do the rebase and fix any merge conflicts.
  3. 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.
  4. Push your to your fork of Habitica in GitHub using the same command you used for the original push:
    git push origin name-of-your-branch
    That will automatically update your PR.
    • 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 -f:
      git push -f origin name-of-your-branch
    • Note that as a general rule you should be cautious about using -f 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 -f before you use it.
  5. 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 PRsEdit

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 PREdit

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 CycleEdit

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 develop 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 develop 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.

Ad blocker interference detected!

Wikia is a free-to-use site that makes money from advertising. We have a modified experience for viewers using ad blockers

Wikia is not accessible if you’ve made further modifications. Remove the custom ad blocker rule(s) and the page will load as expected.