FANDOM


IMPORTANT NOTICE FOR ALL DEVELOPERS:

If your local install was made before 24 April 2018, the database needs to be updated. See the "Updating Your Local Install" section in Using Your Local Install to Modify Habitica's Website and API




Coding 3 by phoneix faerie-d7idtti
Blacksmiths 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 then joining the Aspiring Blacksmiths (Habitica Coders) guild to ask any questions you might have. Important announcements that need to be broadcast to all coders can also be found on The Forge, Habitica's blog for blacksmiths.

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 processes for creating code changes.

Ways to HelpEdit

WebsiteEdit

Below are tips for finding items to work on, depending on how you would like to contribute. In all cases, check the notes for the current status of the item and whether anyone else is actively working on it (e.g., if a pull request is linked, someone has already submitted a fix). If someone else has already recently commented to say they are working on a Github issue or Trello card, please leave the work for them. However, if it has been many days since their last comment, they might no longer have time to contribute to Habitica, and then it could be appropriate for you to ask if you can take it over.

Before you start work, it's important that you post a comment on the GitHub issue or Trello card to express your interest in working on it, and then wait for a response from an admin. This is because some issues and feature requests will not always be suitable for actioning (for example during a code refactoring period). This is true even of the issues labeled with the GitHub Labels listed below. Depending on the issue or feature, you might like to describe your suggested approach so that admins can comment on whether it's suitable.

The website's repository uses other labels in addition to the ones listed above. You can read about them in GitHub Labels, but the ones listed above will be of most use in finding useful issues to work on.

Mobile App for iOSEdit

  • The iOS "Habitica" app has its own code base in its own GitHub repository at github.com/HabitRPG/habitica-ios. It is open source and contributions are welcome.
  • If you want to contribute to the iOS app, the Issue list contains a list of already requested features and known bugs. Feel free to look through them to find things you would like to work on. In order to prevent duplicate work, a comment should be left on the issue you intend to work on. If you would like to work on a feature that does not yet have an existing issue, please create one first, so that implementation details can be discussed.

Mobile App for AndroidEdit

  • The Android "Habitica" app has its own code base in its own GitHub repository at github.com/HabitRPG/habitica-android. It is open source and contributions are welcome.
  • If you want to contribute to the Android app, the Issue list contains a list of already requested features and known bugs. Feel free to look through them to find things you would like to work on. In order to prevent duplicate work, a comment should be left on the issue you intend to work on. If you would like to work on a feature that does not yet have an existing issue, please create one first, so that implementation details can be discussed.

BountySource Edit

Some issues will have BountySource bounties on them, posted by staff or users. If your fix for such an issue is accepted, you will be able to claim the money as payment. In all other ways, these issues are treated identically to issues without bounties, so follow all the normal guidelines for them (e.g., asking first if it's okay for you to work on the issue).

Website Technology StackEdit

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, which you can learn here.

Server Edit

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
monk Used for one-off database update scripts ("migrations")
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 Edit

Technology Further Information
Bootstrap
Pug (Jade) Pug (formerly Jade) is used to meet the need for a server-side templating language to allow injection of variables (`res.locals` from Express).

Pug's "significant whitespace" paradigm also protects from committing common HTML errors such as missing or mismatched close tags.

SCSS (SASS)
Vue.js Vue.js provides the responsive frontend for the site. Habitica's admins recommend these learning resources:

Testing Edit

Technology Further Information
Karma Running Unit Tests on Karma

See the Creating and Running Automated Tests section.

Mocha
Travis CI Used to run all the tests for every pull request, and report results.

Services Edit

Technology Further Information
Amplitude Analytics provider, for measuring engagement and retention
Docker Hub Holds images of Habitica's releases for deployment
Microsoft Azure Cloud computing servers

Working with a Local Installation Edit

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.

MongoDBEdit

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 habitrpg

Alternatively, directly start the shell with the database selected:

   $ mongo habitrpg

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)Edit

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

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 StringsEdit

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 StringsEdit

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.

ImagesEdit

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/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/assets/images/sprites/ and website/client/assets/css/sprites/

Other Useful CommandsEdit

Here are various helpful commands.

Search codeEdit

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 SettingsEdit

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 PagesEdit

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.wikia.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 Edit

You're in luck! Blacksmiths do not need to do anything special, like complete a Contributor Tier request (as Scribes are requested to do), 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!

See Also Edit