Blacksmiths (programmers) are vital to the success of Habitica. Your contributions are needed and appreciated! There are several ways to contribute coding expertise to the website and mobile apps. A great first step in getting acquainted with what needs to be done is reading all of this page and the pages it links to.
If you want to contribute code for Habitica's website or API, be sure to also read Setting up Habitica Locally for important information about getting started and then Using Your Local Install to Modify Habitica's Website and API to learn the process for creating code changes.
Ways to Help[]
Website[]
Assistance with the website and API involves fixing bugs or adding features that Habitica's staff have approved as suitable for a contributor to create. To access the list with all of the issues affecting the project, you can find them under the issues tab in the GitHub. Both bugs and features are advertised in the website's GitHub repository and are marked with a "help wanted" label.
It is strongly recommended that you read the GitHub Labels page before selecting an issue to work on. It will explain Habitica's labeling system (e.g., so you can find issues that are easy or of medium difficulty, or otherwise relevant to your interests) and will give you links to the issues categorized with each label.
Before starting work on a bug or feature:
- Check that the issue has the "help wanted" label. Other issues will be in progress, on hold, or otherwise unsuitable for a contributor to work on. (If you think that an issue not marked with "help wanted" may be suitable for you, it's acceptable to ask as described below, but you should always wait for a reply before starting to code!)
- Read the issue's description and all comments in it to ensure you understand the issue and the fix or feature required.
- Look at the most recent comment to see if another Blacksmith has already asked to work on it; if so, leave it for them.
- Post a comment on the issue to state that you would like to work on it.
- Depending on the issue or feature, you may wish to describe your suggested approach so that admins (staff) can comment on whether it's suitable. If you're not sure if this is needed, you don't have to; admins will ask if they do want that information.
- Wait for an admin to say that you can proceed. In some cases even "help wanted" issues are not suitable for fixes (e.g., if the issue has already been fixed and was not correctly re-labelled and closed), so waiting for approval will prevent your coding time being wasted!
- If you have posted to ask to work on an issue and have not received a reply after three or four days, please post again!
Please be aware that if you start work on an issue without receiving a reply first, your efforts might be wasted if it is decided that the issue is no longer suitable for a fix.
Tests for the Website and API Code[]
As described in Using Your Local Install to Modify Habitica's Website and API, Habitica's website and API code includes a test suite.
Additions or improvements to those tests are always welcome! If you see a place where you think test coverage could be improved, the best approach is to send an email with your suggested improvements to [email protected] (you can do this by going to Help > Report a Bug) and wait for an admin to respond. They will either say that you can proceed or will create a GitHub issue where further discussion can occur.
Mobile Apps for iOS and Android[]
Contributing to the mobile apps falls under the title Fletcher, though there are some similarities to Blacksmith contributing here. To learn more about becoming a Fletcher, read the Guidance for Fletchers page for Android or iOS.
Creating your own Feature[]
If you have in mind a feature for the website or mobile apps that does not already have a GitHub issue, please suggest the feature using the Habitica User Feedback and Suggestions form, which is available from Habitica's website at Help > Request a Feature and on the mobile apps at Menu > "Help & FAQ". State in your request that you are a programmer and would like to create the feature yourself. Include your contact details and wait for a staff member to contact you to say that your request is approved.
Please be aware that it may take several months for approval as staff need to manage feature requests to ensure that the website and mobile apps remain consistent and easy to use.
Your contact details can be an email address or your Habitica User ID. (If you wish to you may also include your Habitica @Username or Display Name but it is essential that you also include an email address or User ID so that if you change your names, staff can still contact you.)
Please be aware that if you create a feature without first receiving approval, your feature might not be accepted and your efforts may be wasted. Even though Habitica is open source, Habitica's staff need to approve all features to ensure that they fit with existing features and all future planned features.
Website Technology Stack[]
The technologies Habitica uses for its website are listed below. You don't need to be familiar with all of them, or even most of them, to be able to contribute! Some links to high-quality learning material are also included. Many of these technologies (namely, the ones with '.js' or 'JS' in the name or URL) are based on the programming language JavaScript.
Server[]
| Technology | Further Information |
|---|---|
| ExpressJS | |
| Node.js | How do I get started with Node.js
nodeschool -- a particularly useful entry-level interactive Node curriculum. |
| MongoDB | Official MongoDB documentation
See also the MongoDB section below for some brief tips. |
| MongooseJS | |
| Gulp | You can learn about this at the Gulp GitHub page. |
| Git and GitHub | Pro Git -- Taking the time to read this excellent resource will help you become more comfortable with Git.
git-it -- This fun and interactive part of the nodeschool curriculum will help with learning Git and GitHub. (Scroll down for more information.) |
| ESLint | Eslint config for HabitRPG projects |
Client[]
| Technology | Further Information |
|---|---|
| Bootstrap | |
| SCSS (SASS) | |
| Vue.js | Vue.js provides the responsive frontend for the site. Habitica's admins recommend these learning resources:
|
Testing[]
| Technology | Further Information |
|---|---|
| Mocha |
Reverse-Engineered Requirements Documents[]
In June 2019, students from the University of Brasília analyzed Habitica for a project. Their aim was to reverse-engineer Habitica's website to develop requirements artifacts. This section displays two of the Rich Pictures that they developed. A Rich Picture is a way to explore a situation and express it through diagrams, showing its flow. Although these Pictures are not official Habitica documents, they might assist a new code contributor to develop an understanding of the site and aid in development of features and bug fixes. Click each image to see a larger version.
The images were sourced from their project wiki at https://requisitos-habitica.netlify.com.
A Rich Picture showing the general flow of Habitica and how Habitica uses its gamification system to solve the problem of boredom when working on tasks.
A Rich Picture showing the Habitica's Inventory system.
Working with a Local Installation[]
Blacksmiths should create a local running instance of Habitica, for testing and development. The process to create a local instance can be difficult, so we've collected steps for each operating system at Setting up Habitica Locally.
The process of using your local installation to make changes and create pull requests is described in Using Your Local Install to Modify Habitica's Website and API.
MongoDB[]
To learn how to use MongoDB, we recommend reading the official MongoDB documentation or another reliable online resource, but here are a few examples of basic commands to help new developers gain a quick understanding of using MongoDB. You can run these statements in the MongoDB command line interface (CLI) or with a GUI tool such as Robo 3T IDE's IntelliShell.
In the commands below, the $ sign indicates a Unix, Windows or Git Shell prompt and the > sign indicates a Mongo CLI shell prompt. Type only the text that appears after $ or > into your command line.
To access the Mongo shell and then select your local install's Habitica database:
$ mongo > show dbs > use habitica-dev
Alternatively, directly start the shell with the database selected:
$ mongo habitica-dev
View the "collections" in the database ("users", "groups", etc.):
> show collections
View the full "document" for one user in the "users" collection (the user's User ID is 12345678-b5b9-4bb4-8b82-123456789abc):
> db.users.find({_id: '12345678-b5b9-4bb4-8b82-123456789abc'})[0]
View only the preferences object from the user's document:
> db.users.find({_id: '12345678-b5b9-4bb4-8b82-123456789abc'})[0].preferences
Change a value for the user using the update method with $set:
> db.users.update({_id: '12345678-b5b9-4bb4-8b82-123456789abc'}, {$set: {'profile.name':'New Display Name'}})
Using Your Local Install to Modify Habitica's Website and API has advanced examples for specific purposes that are likely to be useful to you when testing your code changes.
Translatable Strings (locales files)[]
Translatable strings appear in files in the website/common/locales/en directory. Each string consists of a key and a piece of text, for example:
'clearAll': 'clear all items',
Do not edit files in other directories under website/common/locales because all translations are managed in Weblate.
Always test your string additions and edits by viewing them in your local install. Never merely assume that even simple string additions will work as expected.
Adding Translatable Strings[]
When your change adds text that will be seen by players, you should add it as a translatable string so that users in all languages can benefit from it. There are rare exceptions to this (such as error messages that should be visible to only programmers using the API) but typically an exception would be described in the issue you are working on.
To add a new translatable string write it in a Vue or JavaScript file using the t function. For example:
env.t("newKey")
i18n.t('newKey')
Find existing strings in the file you are modifying for examples.
Then, in the website/common/locales/en directory, edit the appropriate json files, adding the new string as follows:
'newKey': 'String Title',
If there are already strings in the json file about the same topic, then it's preferred that you add your new string in the same place as the existing ones, to keep similar strings together.
If there are no similar strings, add yours at the end of the file. Add a comma to the existing string that used to be the last string in the file. Do not add a comma to the end of your final string.
Modifying Translatable Strings[]
Existing strings can be changed whenever necessary.
Do not change the keys unless there's a good reason to do so. For example: if you needed to change the string 'clear all items' to 'delete all items', you would not also change its key 'clearAll' to 'deleteAll', since the meaning of the original key is still accurate.
The reason the keys are usually not changed is because they can be referenced in more than one place in Habitica's code and so all of those pieces of code would need to be updated; this is undesirable unless there's a good reason for it. In addition, when a key is changed the translators need to redo the translations without having the original translation visible for comparison. Note that when there is a reason to change the keys, you still should not modify the locales directories for languages other than English.
Images[]
For information about creating new images for Habitica, see Guidance for Artisans.
When a new image has been prepared and approved by the staff, an issue will be created to request it be added to Habitica. A Blacksmith will then need to add it to the repository. Most images will need to be copied into suitable subdirectories under website/client/src/assets/
After adding new images or new versions of existing images, run npm run sprites to recompile the image spritesheets.
Sometimes, this command will result in a new spritesheet being created, in which case use git add to add the new files. You will find them under website/client/src/assets/css/sprites/
Other Useful Commands[]
Here are various helpful commands.
Search code[]
You'll often want to search all files containing some keyword or string, to determine what files need to be edited when adding/editing some feature. Use the grep command (search online for information about grep on your operating system) or the git grep command (git documentation will teach you about how to use it).
Preference Settings[]
Habitica has preference settings for the users to customize the website's behavior. New settings may be added if necessary. Please do not add settings only a small proportion of users are likely to use, or settings for trivial customizations. Instead choose a behavior the majority of users are likely to enjoy.
Too many preferences makes the settings screen look cluttered and increases the appearance of complexity. If you're uncertain about whether a preference setting is desirable, you can discuss it in the relevant GitHub issue or pull request.
When a new user preference setting is necessary, it can be added to file(s) under website/server/models/user/. Generally, the database will then pick them up the new setting automatically and add it to user accounts as necessary. If it is ever necessary for the database to be modified manually, admins can do that.
"Information for Developers" Sections on General Wiki Pages[]
At the bottom of some wiki pages, are sections called Information for Developers. These contain useful tips for Blacksmiths related to the content on that page.
The information is hidden behind a spoiler-style show/hide toggle button so it doesn't clutter the page for non-technical users.
The sections use the {{InfoForDevs Start}} and {{InfoForDevs End}} templates to ensure correct formatting and wording for the buttons and other text. To see how that is done, open any page with an Information for Developers section in the source editor.
To see a list of all pages with this section, use the "What links here" tool for the 'Start' template.
To see all Information for Developers sections unhidden by default:
- Create a Wikia account if you don't already have one.
- Edit your personal Wikia css file, located at: http://habitica.fandom.com/wiki/User:YOUR_USERNAME_HERE/wikia.css
- Insert these lines into CSS file:
/* Force all "Information for Developers" sections to always be visible */
.habitrpg-InfoForDevs {
display:block !important;
}
.habitrpg-InfoForDevs-hideIfDev {
display:none;
}
You can see an example at User:LadyAlys/wikia.css
Contributor Tier Process[]
You're in luck! Blacksmiths do not need to do anything special, like complete a Contributor Tier request, in order to earn Contributor Tiers. Contributor Tiers for Blacksmiths will be granted by the admins as they review and accept Blacksmith submissions. Admins will track Blacksmith contributions for credit toward future Contributor Tiers.
The first one or two Contributor Tiers from Blacksmithing are fairly easy to get, and you might find that a single pull request being completed is enough for each of them. The higher tiers require progressively more work, and several successful pull requests might be needed. Admins will record each pull request when it is completed, and will award a tier when enough contributions have been made.
Generally, when a PR is merged, an admin will write in both the PR and Hall of Heroes something like "I've given you Tier x" or "Noted toward your next contributor tier." If they write something like the latter, it means that PR alone was not enough for a tier by itself, or not enough to increase your tier to the next level if you already had other partial credit towards it. If an admin does not make any comment on your PR about credit towards contributor Tiers, please post to the PR to ask about it! Admins sometimes do forget and they always appreciate a gentle reminder because giving contributors credit for their work is important!
Note that the contributor tier may not be added until some time after a PR is merged so the code has time to go through testing. It should be added by the time the changes are released to production.[1]