a new page for Blacksmiths; still in development
New page
{{Underconstruction}}
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. -- [[User:LadyAlys|LadyAlys]] ([[User talk:LadyAlys|talk]]) 03:37, February 19, 2017 (UTC)
To contribute code to Habitica's [https://habitica.com 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 [https://habitica.com/#/options/groups/guilds/68d4a01e-db97-4786-8ee3-05d612c5af6f 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 <code>npm install</code>
* 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 [https://github.com 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, [https://git-scm.com/docs/git-commit commit] them or [https://git-scm.com/docs/git-stash stash] them.
# [https://git-scm.com/docs/git-checkout Checkout] the `develop` branch and [https://git-scm.com/docs/git-rebase rebase] it:
## <code>git checkout develop</code>
## <code>git fetch upstream</code>
## <code>git rebase upstream/develop</code>
# Compare your local config.json file with the config.json.example file (e.g., <code>diff config.json.example config.json</code>). If there are any changes, apply them to config.json (e.g., <code>cp config.json.example config.json</code>). 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 <code>npm install</code>. Carefully review the output for errors and resolve the errors before continuing.
# Run <code>npm test</code>. 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 [https://habitica.com/#/options/groups/guilds/68d4a01e-db97-4786-8ee3-05d612c5af6f Aspiring Blacksmiths] guild and then wait for them to be resolved before proceeding further. Errors at this point are serious!
# Run <code>npm start</code> and briefly test that the http://localhost:3000/ website works.
# Checkout the branch you are using for your changes. Tip: <code>git checkout -</code> (note the hyphen) will switch between your current branch and the previous one you were using.
# Use [https://git-scm.com/docs/git-diff git diff] to examine the differences between your branch and the `develop` branch: <code>git diff upstream/develop</code>. 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:
## <code>git rebase upstream/develop</code>
## [https://git-scm.com/book/tr/v2/Git-Branching-Basic-Branching-and-Merging#_basic_merge_conflicts Fix any merge conflicts] that might exist.
## 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.
==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 <code>develop</code> 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:
## <code>git fetch upstream</code>
## <code>git checkout -b name-of-your-branch upstream/develop</code>
# Start coding! :)
# When you have progressed far enough that you want to make a [https://git-scm.com/docs/git-commit commit], please 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.
# If you want to change to a new branch when you are not ready to commit, you can [https://git-scm.com/docs/git-stash stash] them.
# Before submitting your code for review, test it thoroughly in your local install (refer to the "Run Habitica" section in [[Setting up Habitica Locally]] for details).
# If your code changes any user-visible parts of the website, take screenshots that show all of the changes.
# Run the automated tests (<code>npm test</code>) and fix any errors. If you suspect that errors might not be caused by your code, investigate that by testing in the <code>develop</code> branch (see the process in "Updating Your Local Install" above for details).
# 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 <code>develop</code>:
## <code>git fetch upstream</code>
## <code>git rebase upstream/develop</code>
## [https://git-scm.com/book/tr/v2/Git-Branching-Basic-Branching-and-Merging#_basic_merge_conflicts fix any merge conflicts]
## 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: <code>git push origin name-of-your-branch</code>
# In GitHub, create a pull request (PR).
## Always 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.
## 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.
## 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 Cheat Sheet|markdown]] to insert an image from a file sharing site.
## 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 [https://docs.travis-ci.com/ 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 <code>develop</code> 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 <code>npm test</code> 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 <code>develop</code> 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 <code>upstream/develop</code> 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_Rewards|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 [https://github.com/HabitRPG/habitica/releases 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 <code>release</code> branch that allows for a longer testing period before contributor's changes are made live. This wiki page will be updated with details.