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

Wiki editors: This page will undergo many changes and will probably be renamed. Don't create links to it until you see that this message has been deleted. It's probably also not worth your time yet to polish the language or fix spelling mistakes, grammatical errors, typos, etc, as I'll find most of them while I'm working on this. You'll see material from other pages being duplicated here but don't remove it from the other pages; I'll do that when I've finished writing this page. -- LadyAlys (talk) 03:37, February 19, 2017 (UTC)

To contribute code to Habitica's habitica.com website, 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 any given change to the website. 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.

Some important points:

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, every time the node modules are updated, you'll see a message there advising you to run npm install
If you exeperience 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, it is recommended that you 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 more than a few hours have 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.

If you have uncommitted changes, commit them or stash them.
Checkout the `develop` branch and rebase it:
1. git checkout develop
2. git fetch upstream
3. git rebase upstream/develop
Compare your local config.json file with the config.json.example file (e.g., diff config.json.example config.json). If there are any changes, apply them to config.json (e.g., 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.
Update any node packages by runnning npm install. Carefully review the output for errors and resolve the errors before continuing.
Run npm test. There should be no errors since at this point you are using Habitica's official `develop` codebase, but if you do see errors, please report them immediately in the Aspiring Blacksmiths guild and then wait for them to be resolved before proceeding further. Errors at this point are serious!
Run npm start and briefly test that the http://localhost:3000/ website works.
Checkout the branch you are using for your changes. Tip: git checkout - (note the hyphen) will switch between your current branch and the previous one you were using.
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.

There are shortcuts that you can take in this process, as you'll realise once you are more familiar with Habitica's code and with git, however it's recommended that you follow this full process while you are still new to coding for Habitica or at any time that you experience a problem with your local install that you don't understand. This full process will ensure that your system is up to date and will help to identify which parts of your system contain code that might be causing problems.

Random notes for merging above/below

refer to the "Rebase Branch" section in Using Habitica Git.

If node modules or bower components have been updated in Habitica, you will need to update them in your local install by rerunning "npm install" - if this is necessary, you should see errors about missing modules. Ask in the Aspiring Blacksmiths (Habitica Coders) guild if you need help. Further instructions will be added to the wiki later.

Post Installation troubleshooting might help if your local Habitica installation stops working after a while.

Creating a Change

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

If you have not yet decided what change to make, refer to "Ways to Help" > "Website" in Guidance for Blacksmiths.
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.
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
Start coding!
Create automated tests for every aspect of your new or modified code. Ideally, you would create these tests before you start coding the new feature or bug fix, then confirm that the tests fail with Habitica's unmodified code base, and then write the code needed to make the tests pass.
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.
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

Before submitting your code for review, you must test it thoroughly in your local install.

Run the existing automated tests (npm test) and fix any errors that are reported. If you suspect that errors might not be caused by your code, investigate that by testing in the develop branch (see the process in "Updating Your Local Install" above for details).
Create new automated tests to test every aspect of your feature or bug fix and ensure your tests pass.
Test all aspects of your feature or bug fix manually in your local install by running npm start and using your localhost website (refer to the "Run Habitica" section in Setting up Habitica Locally for details).
If you need to make code changes after doing npm start,

Restarting the Local Webserver

The npm start command starts a webserver that uses the current code in your local install. When you change that code code, you can make the local website use the new changes by manually stopping the webserver with Ctrl-C and restarting it by running npm start again.

However to make restarting more convenient, the local Habitica webserver uses nodemon. It watches the source code in your local copy of the repository and automatically restarts the webserver 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 webserver 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.

Using the Debug Menu

The following menu is in the footer of every page of your local installation, and can be used to quickly trigger certain actions, making testing your code faster and more efficient.

Submit your Change for Review

If your code changes any user-visible parts of the website, take screenshots in your local website to show all of the changes.

Commit any uncommited changes (use a meaningful commmit message).
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 if any code related to your change has been modified by the rebase
Push your commit(s) to your fork of Habitica in GitHub: git push origin name-of-your-branch
In GitHub, create a pull request (PR).
1. Always give your PR a meaningful title that describes the bug being fixed or the feature being created / modified.
2. If your PR will fully fix an issue, add "fixes [URL of issue]" to the end of the title.
3. If your PR will partially fix an issue, add "partial fix for [URL of issue]" to the end of the title.
4. Follow the instructions that you'll see in the comment field of the PR. Always write a meaningful explanation of your change - do not rely on the title explaining it fully.
5. If your change has a visible effect on the website, include screenshots. You can drag image files into the comment, or paste an image from your screenshot tool, or use markdown to insert an image from a file sharing site.
6. 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.
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 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.

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 might request changes, in which case, 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 the "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 is optional but experienced contributors often make good suggestions. If you notice than 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 recommmended that you do implement the suggestion or explain why you think it should not be implemented.

If other changes are merged to develop while your pull request is being reviewed, admins might ask you to fix merge conflicts. This can be done in your local install by rebasing from upstream/develop as described above.

If you need to make changes to your code or rebase, you should do that in the branch you created in your local install, then commit with an appropriate commit message, and then push to the same branch in GitHub. This will automatically update your pull request with your changes.

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.

Acceptance

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. 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 a few days before it appears in Habitica's production website. During this time, admins will use the staging site for as much of their normal use of Habitica as possible to notice any errors that might have been missed during testing (e.g., if other PRs have negative interactions with your PR). 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.

Note that soon there will be a new process involving a release branch that allows for a longer testing period before contributor's changes are made live. This wiki page will be updated with details.