Guidance for Blacksmiths
this wiki
Be sure to also read Setting up Habitica Locally for important information about getting started.
Ways to Help
Edit
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 issue and whether anyone else is actively working on it (if a pull request is linked, someone has already submitted a fix).
It is strongly recommended that before you start work, you post a comment on the GitHub issue or Trello card asking about the status of the item and expressing your interest in helping resolve it, and then wait a couple of days to see if there are any responses. This is because some issues and feature requests are not suitable for working on because Habitica's chief developers are currently making some large-scale changes to some parts of the code, which will partially or fully fix some issues. This is true even of the issues labeled with the GitHub Labels listed below.
If someone else has already recently commented to say they are working on an 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 starting work on an issue or feature, you might like to describe your suggested approach so that we can comment on whether it's suitable.
- I want to start small: Check out the Github issue queue and search for items labeled type: entry level coding for issues where you can ask to contribute.
- I want to help where I'm most needed: Search for Github issues labeled status: issue: help welcome now, priority: critical, and priority: important and ask to contribute before starting. Solving a bug labeled priority:critical will allow you to earn the Critical Hammer of Bug-Crushing.
- I want to create unit tests & Karma tests!: Welcome, bug-slayer! Please refer to the Tests section for further information.
- I want to build things!: Make way for the new hero! Check out the Trello feature queue. It is important that you ask first to find out if a feature request you select is approved by the staff. Some feature suggestions are not suitable for implementation and a pull request that implements them would not be accepted.
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
- Please email mobile@habitica.com to discuss what work you'd like to do with our main mobile developers.
- The iOS "Habitica" app has its own code base in its own GitHub repository at github.com/HabitRPG/habitrpg-ios. It is open source and contributions are welcome.
- The old iOS "HabitRPG" app is no longer under development and contributions will not be accepted.
Mobile App for AndroidEdit
- Please email mobile@habitica.com to discuss what work you'd like to do with our main mobile developers.
- The Android "Habitica" app has its own code base in its own GitHub repository at github.com/HabitRPG/habitrpg-android. It is open source and contributions are welcome.
- The old Android "HabitRPG" app is no longer under development and contributions will not be accepted.
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 -- included in the Stack Overflow article linked above, but a particularly useful entry-level interactive Node curriculum. See the Angular/Node/Pug Tips and Best Practices section. |
| MongoDB | See the MongoDB section. |
| MongooseJS | |
| monk | |
| Bower | |
| Gulp | Check out the Gulp GitHub page to get started. |
| 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 |
|---|---|
| AngularJS (Angular 1) | Habitica will stop using Angular in future, so if you are considering learning Angular specifically to help with Habitica, you might want to not spend too much time learning it in great depth. Vue.js will be used instead. Shaping up with Angular.js -- A video tutorial series with accompanying exercises. Completing the exercises as well as viewing the videos is recommended to understand Habitica's AngularJS code. Learn Angular -- Free interactive lessons. See the Angular/Node/Pug Tips and Best Practices section. |
| 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. See the Angular/Node/Pug Tips and Best Practices section. |
| Stylus | Standard CSS was insufficient for our app, so Stylus was adopted. |
| Vue.js | Vue.js is not currently used with the production code but will be used in future to replace Angular.js. Habitica's admins recommend these learning resources:
|
Testing Edit
| Technology | Further Information |
|---|---|
| Karma | Running Unit Tests on KarmaSee the Tests section. |
| Mocha | |
| Selenium | Used only for an end-to-end test of the static home page. |
| Travis CI | Used to run all the tests for every pull request, and report results. |
Services Edit
| Technology | Further Information | ||
|---|---|---|---|
| New Relic | |||
| Heroku | |||
| Amazon Web Service (AWS) | |||
| Amplitude |
API ChangesEdit
On 21 May, 2016, version 3 of Habitica's API was released. Version 2 no longer works. Information about the new API is available at Application Programming Interface. Questions can be asked in the Aspiring Blacksmiths (Habitica Coders) guild. Important announcements on the API changes can also be found on The Forge, Habitica's blog for blacksmiths.
If you have a local install that was created when version 2 was in use, delete it and follow the process in Setting up Habitica Locally to create a new local install.
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
These are quick tips for new developers to get the hang of using the Mongo database. In the commands below, the $ sign indicates a Unix, Windows or Git Shell prompt and the > sign indicates a Mongo shell prompt. Type only the text that appears after $ or > into your command line.
Access a shellEdit
Start the mongo shell then select the database:
$ mongo > show dbs > use habitrpg
Alternatively, directly start the shell with the correct database:
$ mongo habitrpg
Use the shellEdit
View the "collections" in the database ("users", "groups", etc):
> show collections
Find your test user and examine its data. From localhost settings, copy the User ID, then run this command:
> db.users.find({_id: '85b007a2-b5b9-4bb4-8b82-e4567edb4919'})[0]
Want to see the preferences only?
> db.users.find({_id: '85b007a2...'})[0].preferences
To update something for your user, use the update method with $set. For example, edit your profile blurb:
> db.users.update({_id: '85b007a2...'}, {$set: {'profile.blurb':'test'}})
Give yourself 10 gems (can also be done from the Debug menu in the lower right of the footer):
> db.users.update({_id: '85b007a2...'}, {$set: {'balance':10}})
Get admin rights (you will then see extra options in the Hall):
> db.users.update({_id: '85b007a2...'}, {$set: {'contributor': {'admin':1}}})
Assign yourself unpurchasable quest scrolls (e.g., for limited edition quests):
> db.users.update({_id: '85b007a2...'}, {$set: {'items.quests': {"egg":2,"basilist":1,"evilsanta":1,"evilsanta2":1}}})
This gives the user two Egg Hunt scrolls and one scroll each for another three quests. Please note that this will clear all other quest scrolls that the user possesses. Other scrolls can be added in the same way (respective keys can be found in common/script/content/index.js, although this file name is likely to change soon because the code is being refactored) or can be purchased later from the market.
Creating a local user account identical to your production site accountEdit
Export your user data using the GET /user API route, and import it locally using MongoDB commands such as db.collection.insert(). This can be a fast way to create a local account prepopulated with tasks, equipment, currency and inventory.
Your account will need to be inserted into the users collection, but this collection won't exist in Mongo until an account is created in your local install. To do this, start your local install and create a test account, and then insert your production account.
The API does not export some authentication information for security reasons, so you will need to set it after inserting your user data. The command below sets the password to "test" and creates an API token:
> db.users.update({'auth.local.username': 'your-username'}, {$set: {'auth.local.salt': '7eff6ff32a', 'auth.local.hashed_password': '5b5d5f748091e62aadf2f109f4a7379d2d8653dc', 'apiToken': '48ed9d70-0adf-431d-a001-1cb12d57590e'}});
Warning! Do not use the same API token or password that are used for your production site account!
If you ever need to seek support for your local install or report information from it, you might include the full authentication data, and if it were the same as for your production account, the security of your production account would be compromised. The token used in the example above was randomly generated and is safe to use in your local install.
MigrationsEdit
Some Habitica website changes require existing user accounts to be modified (e.g., to assign a default value for a new setting to all users). Such database changes are done with a migration script, which contains JavaScript that connects to the database and makes modifications. All migration scripts are in migrations/. Read them and use them as examples to write your own script. The more recently edited scripts are likely to contain better, more up-to-date code than older scripts.
To test a migration script:
$ mongo habitrpg migrations/name_of_script.js
Angular/Node/Pug Tips and Best PracticesEdit
Data Binding, and Template ConditionalsEdit
When working in the Pug templates, you may see element attributes such as ng-class, ng-show, or ng-if. These are bindings used to map model data to elements for display that are part of AngularJS. These bindings can be used to define styles or display elements based on conditionals.
You may also notice some other attributes such as bo-class or bo-if.... so what's the difference?
Bindings that begin with "ng" are part of Angular and are completely dynamic. This means every time something changes with the app, Angular will test all of these bindings with conditionals and take action again. Obviously this is a concern for performance.
Sometimes the data used to calculate these conditionals will not change often, if ever. In that case, we have an option for static binding, using a library called Bindonce. These are similar bindings, but they are only checked at the initial load of the application.This is the preferred method of binding as long as the data will not change.
Bindonce directives should only be used when the model data being used for the conditional will not change during a session, or will change infrequently enough that it's not unreasonable to expect the user to refresh the page. If this is not the case, then stick with traditional binding. If you can't decide or have no idea what you just read, just use the ng-<whatever> attributes.
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',
Adding Translatable StringsEdit
To add a new translatable string write it in the jade file as follows:
env.t("stringLabel")
Then, in the website/common/locales/en directory, edit the appropriate json files, adding the new string as follows:
'lastLabel': 'Add a comma at the end of this line',
'stringLabel': '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.
Do not edit files in other directories under website/common/locales because all translations are managed in Transifex.
To test the string:
- stop npm if it is running (Ctrl-C)
- run
npm start
Modifying Translatable StringsEdit
Existing strings can be changed whenever necessary. Only change the strings in the website/common/locales/en directory, never in any of the other language directories.
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.
TestsEdit
Refer to Using Your Local Install to Modify Habitica's Website and API for information about tests.
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 common/img/sprites
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 common/dist/sprites (look for a *.png and *.css file for each spritesheet).
Other Useful CommandsEdit
Here are various helpful commands.
Search codeEdit
In the console, type:
grep -R "STRING" *
To search for STRING in all files in the current directory and all the directories within it.
To make a search case insensitive (STRING or String or string etc), add -i
grep -iR "STRING" *
You'll often want to search all files containing some keyword, in order to determine what files need to be edited when adding/editing some feature.
The grep command also takes a regex as its search parameter:
grep -R "REGEX" *
Read more about grep and regex here.
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 Aspiring Blacksmiths (Habitica Coders) guild or in a relevant Github issue or pull request.
Tip for storing preferences Edit
When a new user preference setting is necessary, it can be added to website/src/models/user.js. 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.
Generating Shrinkwrap Edit
Shrinkwrap is how we manage to lock in dependency versions for npm modules. This helps when deploying or distributing the app to multiple sources. The shrinkwrap file will update automatically if you use --save, but if you need to recompile manually, follow these steps:
- Run
npm prune - Run
npm shrinkwrap
"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 pull requests might be needed. Admins will record each pull request as it is made and will award a tier when enough have been made.
