Внесение изменений в сайт Habitica и API с помощью локальной копии

Перед началом работы над изменениями сайта Habitica habitica.com и API, прочтите инструкции из статьи «Установка Habitica локально». Как только ваша локальная копия заработает, здесь вы сможете узнать как устроен процесс внесения изменений. Обращайтесь к этой странице каждый раз, когда начинаете новое изменение или когда у вас возникают проблемы с локальной копией.

Эта страница не имеет отношения к разработке мобильных приложений.

Общие замечания

• Прочтите «Руководство для кузнецов».
• Вступите в гильдию Aspiring Blacksmiths и будьте в курсе всего что там обсуждают, пока вы работаете над Habitica. Все важные объявления появляются там. Например:
  • Когда обновляются зависимости Habitica, появится совет выполнить npm install (см. раздел «Обновление локальной копии» ниже для понимания всего процесса).
  • Когда на сервер Habitica добавляются новые переменные окружения, появится совет обновить копию config.json, сравнив её с config.json.example.
• Если вы столкнетесь с какими-либо ошибками в любой из инструкций на этой странице, устраните их, прежде чем идти дальше. При необходимости обратитесь за помощью в гильдию Aspiring Blacksmiths.
• Вы иметь представление что такое git и GitHub. В руководстве для кузнецов есть ссылки на общую документацию и соответствующие разделы представленные ниже, чтобы вы могли узнать о любых командах git, которые вы не понимаете.
• Если что-то на этой странице кажется вам неправильным или запутанным, спросите в Aspiring Blacksmiths. Если вы точно уверены, что что-то некорректно, вы можете редактировать эту страницу!
• Когда вы ищете информацию, относящуюся к определенной части Habitica, перейдите на вики-страницы по этой темы, и проверьте наличие раздела Информация для разработчиков внизу страницы. Для получения более подробной информации об этих разделах и о том, как их лучше всего использовать, см. раздел «Информация для разработчиков» на других страницах вики в руководстве для кузнецов.

Обновление локальной копии

If your local install was made before 24 April 2018, the database will not be consistent with the new code. There are two ways to fix this:

• Delete the database by running
  mongo habitrpg --eval "db.dropDatabase()"
  A new database will be created automatically when you next start Habitica. This is a good option if you don't have any test data that you want to keep using.
• Run a migration script to convert the database. The migration script is migrations/groups/migrate-chat.js and it needs to be run from within a migration runner script (migrations/migration-runner.js).
  1. Change to the top-level directory of your local install (the directory where the config.json file exists).
  2. Open the file migrations/migration-runner.js in a text editor.
  3. Find the comment // Replace this with your migration near the bottom of the file. The next line will be const processUsers = require('./a/path/to/a/script.js');
  4. Edit that line so that the path to the script is ./groups/migrate-chat.js -- i.e., when you have finished editing the script, the line must look like this:
     const processUsers = require('./groups/migrate-chat.js');
  5. Save your change and quit the editor.
  6. Run the migration by executing this command:
     node migrations/migration-runner.js

If your local install was made before October 2017, delete it and go through the full installation process described in Setting up Habitica Locally.

If a day or more has 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, or if you've been working on a change for several days and you think your local install might not have the latest code.

1. If you have uncommitted changes, commit them or stash them.
2. Checkout the develop branch and rebase it:
   1. git checkout develop
   2. git fetch upstream
   3. git rebase upstream/develop
3. Compare your local config.json file with the config.json.example file and if there are any changes, apply them to config.json:
   diff config.json.example config.json
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.
4. Update any node packages by running npm install. Carefully review the output for errors and resolve the errors before continuing.
5. Start the local server using the instructions in "Start the Habitica Web Server" section in Setting up Habitica Locally and test that the website works.
6. If you already have a branch that you have been using to make changes:
   1. Checkout the branch: git checkout name-of-your-branch
      Tip: git checkout - (note the hyphen) will switch between your current branch and the previous one you were using.
   2. 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 fetch upstream
      2. git merge upstream/develop
      3. Fix any merge conflicts that might exist.
      4. Reapply changes that you stashed, if any.

Обновления, необходимые с марта 2018

If your local install was last updated before March 17 2018, also follow these steps:

1. delete the node_modules directory and the package-lock.json file (they are in the top-level directory of your install)
2. upgrade node to version 8 (do not change npm; it must remain at version 5)
3. fetch the latest content from upstream/develop
4. run npm install

Создание изменения

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

1. If you have not yet decided what change to make, refer to "Ways to Help" > "Website" in Guidance for Blacksmiths.
2. 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 before you start. Depending on the issue or feature, you might like to describe your suggested approach so that admins can comment on whether it's suitable. If an admin doesn't reply after three days, post a reminder in the same place.
3. Create a new branch in your local install for this change, choosing any name you wish for your branch. Don't do any development in the develop branch because 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
4. Start coding!
5. 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.
   • Remember that if you are adding new files to the repository, you will have to use git add on those files before you commit them.
6. 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.

Тестирование изменений вручную

Before submitting your code for review, log in to the website in your local install and test your feature or bug fix thoroughly.

• Refer to the "Start the Habitica Web Server" section in Setting up Habitica Locally for how to get the website working locally.
• If you need to make code changes after starting the local site, refer to "Restarting the Local Web Server" below.
• Test all aspects of your new code in the website (and/or by using direct API commands if you have modified the API).
• Also test any existing features that are related to the code you've changed to ensure that they are still working as intended. For example, if you are modifying the task editing screen, you might want to check that editing challenge tasks and group plan tasks has not been affected inappropriately.
• In the footer of your local install's website, there is a debug menu with several useful tools for quickly modifying a test account (e.g., giving all mounts to the account). This can make testing your code faster and more efficient. Experiment with the menu items to find out what each one does.

Перезапуск локального веб-сервера

The commands listed in the "Start the Habitica Web Server" section in Setting up Habitica Locally will start a web server that uses the current code in your local install. When you change that code, you can make the local website use the new code by manually stopping the processes with Ctrl-C and restarting them as described in that section.

However to make restarting more convenient, the local Habitica web server uses nodemon. It watches the source code in your local copy of the repository and automatically restarts the web server when the code changes. This means that you usually don't need to do Ctrl-C and a restart.

You can also force nodemon to restart the web server 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:

[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 restart the processes.

Тестирование изменений документации API

If you will be modifying the API documentation, you will want to access the local copy to confirm that your changes display correctly. Run npm run apidoc to compile them once and view them at http://localhost:8080/apidoc/ (replace 8080 with the appropriate number if your local install uses a different port).

If you would like the documentation to be automatically recompiled every time you save a change to the API's files, run npm install -g gulp-cli using sudo on a Unix/Linux/MacOS host or Administrator on a Windows host, and then in each editing session run gulp apidoc:watch

Создание тестовых данных

Manual tests of your changes are likely to require user accounts or guilds with specific characteristics. Many changes to user accounts can be made using the Debug menu in the footer of your test website but some changes to users or guilds can only be made by modifying the documents in the users and groups collections in the database. Below are some examples. If you are not familiar with MongoDB, see the section of that name in Guidance for Blacksmiths (e.g., for information about using its CLI or GUI tools).

To add a one-month gift Subscription to a user, where the user's User ID is 12345678-b5b9-4bb4-8b82-123456789abc:

> db.users.update({_id: '12345678-b5b9-4bb4-8b82-123456789abc'}, {$set: {
    'purchased.plan': {
            'owner': "12345678-b5b9-4bb4-8b82-123456789abc",
            "dateCreated"    : new Date("2017-12-25T01:00:00.000Z"),
            "dateUpdated"    : new Date("2017-12-25T00:00:00.000Z"),
            "dateTerminated" : null, // or you can add a date using the same format as above if needed for your testing
            "gemsBought" : 0,
            "extraMonths" : 0,
            "quantity" : 1,
            "mysteryItems" : [ ],
            "consecutive" : {
                "count" : 1, "offset":0,  "gemCapExtra":0,  "trinkets":0,
            },
            "customerId" : "Gift",
    },
}})

To add Mystery Items to the gift box for a user, refer to the Information for Developers section in Mystery Item.

To add a Group Plan to a group (guild or party), where the group's ID is abcdef12-b5b9-4bb4-8b82-abcdef123456 and the group leader's User ID is 12345678-b5b9-4bb4-8b82-123456789abc:

> db.groups.update({_id: 'abcdef12-b5b9-4bb4-8b82-abcdef123456'}, {$set: {
        "purchased.plan": {
            "owner": "12345678-b5b9-4bb4-8b82-123456789abc",
            "dateCreated": "2017-12-25T01:00:00.000Z",
            "dateUpdated": "2017-12-25T01:00:00.000Z",
            "dateTerminated": null,
            "consecutive": {
                "trinkets": 0, "gemCapExtra": 0, "offset": 0, "count": 0
            },
            "mysteryItems": [],
            "gemsBought": 0,
            "extraMonths": 0,
            "quantity": 3,
            "customerId": "group-unlimited",
            "paymentMethod": "Group Unlimited",
            "planId": "group_monthly",
            "subscriptionId": ""
        }
}})

To add a free subscription from a Group Plan to a user, where the user's User ID is 12345678-b5b9-4bb4-8b82-123456789abc:

> db.users.update({_id: '12345678-b5b9-4bb4-8b82-123456789abc'}, {$set: {
    'purchased.plan': {
            'owner': "12345678-b5b9-4bb4-8b82-123456789abc",
            "dateCreated"    : new Date("2017-12-25T01:00:00.000Z"),
            "dateUpdated"    : new Date("2017-12-25T00:00:00.000Z"),
            "dateTerminated" : null, // or you can add a date using the same format as above if needed for your testing
            "gemsBought" : 0,
            "extraMonths" : 0,
            "quantity" : 1,
            "mysteryItems" : [ ],
            "consecutive" : {
                "count" : 1, "offset":0,  "gemCapExtra":0,  "trinkets":0,
            },
            "lastBillingDate": null,
            "paymentMethod": "Group Plan",
            "customerId": "group-plan",
            "planId": "group_plan_auto",
            "nextPaymentProcessing": null,
            "nextBillingDate": null,
            "additionalData": null,
	},
}})

Написание и запуск автоматических тестов

Habitica has a test suite in the top-level test directory. When Habitica's admins deploy a new version of the website to production, the deployment process runs the tests and refuses to deploy the site if there are any failed tests.

Before you submit your code for review, ideally you should ensure that all existing tests pass. You should also create new tests for every aspect of your feature or bug fix and ensure your tests pass.

However sometimes it is not possible to run the full test suite locally because the tests time out or fail for reasons unrelated to your code. If you are unable to run the existing tests or unsure which new tests you should create, you can submit the code you've written so far for review in a pull request (as described in a section below) and ask for advice about tests.

When you create a pull request, the full test suite is run by Travis CI. If any tests fail, Travis will report the results in your pull request and give a link to the test output. This is a good alternative for testing your code if running the full test suite times out locally. Sometimes even the Travis build times out or reports errors due to temporary problems, in which case admins can restart it to rerun all the tests.

If any failed tests are caused by your code, you will need to modify your code before your pull request can be merged.

The first steps in running tests locally depend on whether you are using Docker or not:

• If you are not using Docker:
  1. Ensure that the MongoDB database server is running.
  2. Stop any npm process such as npm start or any process that is already running tests (don't try to run two test processes at the same time).
  3. Run killall node. This step is not always necessary, but if you have recently run tests and try to run them again, you might see errors such as "before all" hook: callee$2$0 and Error: connect ECONNREFUSED. Killing all node processes will prevent those errors.
• If you are using Docker:
  1. Do not stop the npm processes that are running in your existing containers.
  2. Attach to the habitrpg_client container for test execution by running:
     docker-compose exec client sh
  3. Observe that you now have a bash shell into which you can type commands. The bash prompt will look like this:
     #
  4. Optionally, you might want to create a new container for test execution:
     docker run --name habitica_test -it --volume `pwd`:/usr/src/habitrpg habitica_client gulp test:${your_test_category}:watch
     That command above creates a container called habitica_test, which you can stop and start for running tests.

You are now ready to run one or more of the tests.

Запуск полного набора тестов

To run the full test suite:

1. Change directory into the top-level directory of your local install.
2. Run the entire test suite locally by using npm run test and fix any errors that are reported.
3. If you suspect that errors might not be caused by your code, investigate that by testing in the develop branch:
   1. Commit or stash your changes.
   2. git checkout develop
   3. npm run test
   4. Move back to your own branch with git checkout -
4. Create new tests for all parts of your new or modified code and ensure that they all pass.

Запуск подмножества автоматических тестов

The full npm run test command is equivalent to running, in order:

• npm run lint (lint tests, which help to ensure code quality and consistency)
• npm run test:api:unit (unit tests)
• npm run test:api-v3:integration (integration tests for api v3)
• npm run test:api-v4:integration (integration tests for api v4 - private api)

If one of those fails, the whole npm run test command blocks and fails. You can run each of those commands by itself if you are interested in only one type of test.

While you are editing code or creating tests, it is often convenient to run only the tests that are relevant to your changes.

1. Use .only to mark the test(s) you want to run:
   • To run only a single test, change it('test name', ...) to it.only('test name', ...)
   • To run only one section of tests, change describe('section name', ...) to describe.only('section name', ...). You might find that context is used instead of describe and it can be modified in the same way.
   • .only can be added to more than one test or section, in one or more files, to run all of those tests / sections but no others.
   • Remember to always remove .only before committing your changes!
2. Run either the unit tests or integration tests depending on which files contain the tests you are interested in:
   • if the files are under the test/api/unit/ directory, run the unit tests with:
     npm run test:api:unit
   • if the files are under the test/api/v3/integration/ directory, run the integration tests with:
     npm run test:api-v3:integration

Интеграционные тесты

The integration tests are for testing Habitica's API. They are performed by making HTTP requests to the API's endpoints and asserting on the data that is returned.

Each top level API route has its own integration test directory. For example, all the routes that begin with /groups/ are in /test/api/v3/integration/groups/.

Each file in an integration test directory should encompass a single route and follow this file naming standard:

• begin with the REST parameter for the route (POST, GET, etc)
• display the full name of the route with / replaced by _
• end with .test.js

For example, for the POST route https://habitica.com/api/v3/groups/:groupId/leave, the tests are in the file test/api/v3/integration/groups/POST-groups_groupId_leave.js

If you need to fix errors reported by the integration tests, you might find it helps to run the web server at the same time as the tests so that you can inspect the web server's output caused by the tests. To do that, in one terminal run:
NODE_ENV=test npm start
and then in a different terminal window run:
npm run test:api-v3:integration:separate-server

Промисы в интеграционных тестах

To mitigate callback hell, there is a helper method to generate a user object that can make HTTP requests that return promises. This makes it easy to chain together commands. All you need to do to make a subsequent request is return another promise and then call .then((result) => {}) on the surrounding block, like so:

it('does something', () => {
  let user;

  return generateUser().then((_user) => { // We return the initial promise so this test can be run asyncronously
    user = _user;

    return user.post('/groups', {
      type: 'party',
    });
  }).then((party) => { // the result of the promise above is the argument of the function
    return user.put(`/groups/${party._id}`, {
      name: 'My party',
    });
  }).then((result) => {
    return user.get('/groups/party');
  }).then((party) => {
    expect(party.name).to.eql('My party');
  });
});

If the test is simple, you can use the chai-as-promised return expect(somePromise).to.eventually syntax to make your assertion.

it('makes the party creator the leader automatically', () => {
  return expect(user.post('/groups', {
    type: 'party',
  })).to.eventually.have.deep.property('leader._id', user._id);
});

If the test is checking that the request returns an error, use the `.eventually.be.rejected.and.eql` syntax.

it('returns an error', () => {
  return expect(user.get('/groups/id-of-a-party-that-user-does-not-belong-to'))
    .to.eventually.be.rejected.and.eql({
      code: 404,
      text: t('messageGroupNotFound'),
    });
});

Запуск тестов в Vagrant

If you are running the tests in vagrant, you might see the following error:

Error: /vagrant/.eslintrc:
Configuration for rule "func-style" is invalid:
Value "2,declaration,[object Object]" has more items than allowed.

or many instances of these:

 1:1  error  Definition for rule 'no-empty-pattern' was not found    no-empty-pattern
 1:1  error  Definition for rule 'no-arrow-condition' was not found  no-arrow-condition

You might also find that this test starts but never completes:

Starting 'test:e2e:safe'...

You can avoid those problems by editing two files in the top-level directory of your local install.

• Edit .eslintrc to comment out these lines:
  • "no-empty-pattern": 2,
  • "no-arrow-condition": 2,
  • "func-style": [2, "declaration", { "allowArrowFunctions": true }],

• Edit tasks/gulp-tests.js to comment out this line:
  • 'test:e2e:safe',

Do not commit those changes because those lines are needed for running tests on the server.

Советы

Code formatting and quality: Maintain the coding standards that are already in use in the code base (e.g., two spaces for each indentation level). We use lint to ensure consistent code formatting. When submitting a pull request, an automatic test suite will run over your code and will fail if lint indicates problems. The tests must pass before your code can be accepted.

Gender-neutral language: When writing documentation or code comments, use gender-neutral language (e.g., don't use "he" or "she" or "he/she"). We typically use they / them as a singular pronoun throughout Habitica to cover people of all genders.

Keep your commits clean: Commits must contain only files suitable for inclusion in Habitica's official repository. If you add any files for personal use, never specify them in a git add or git commit command. Also do not specify them in the repository's .gitignore file because changes to that file will be included in the official repository; use your global .gitignore file instead.

Migrations: Some Habitica website changes require parts of the database to be changed (e.g., modifying all existing user accounts to assign a default value for a new setting). 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 (the ones in the migrations/archive directory are less likely to be useful examples unless they have a recent date). Migration scripts need to be run from within a migration runner script (migrations/migration-runner.js). To run a migration:

1. Change to the top-level directory of your local install (the directory where the config.json file exists).
2. Open the file migrations/migration-runner.js in a text editor.
3. Find the comment // Replace this with your migration near the bottom of the file. The next line will be const processUsers = require('./a/path/to/a/script.js');
4. Edit that line so that the path to the script points to the migration you want to run without the "migrations/" portion of the path. For example, if you want to run migrations/groups/migrate-chat.js edit that line to insert ./groups/migrate-chat.js -- i.e., when you have finished editing the script, the line must look like this:
   const processUsers = require('./groups/migrate-chat.js');
5. Save your change and quit the editor.
6. Run the migration by executing this command:
   node migrations/migration-runner.js

Submitting your Change for Review in a Pull Request

When you have finished your change, create a Pull Request (PR) using the process below. You can also do this if you need help with your code or tests, as this is the best way to show your code to Habitica's admins.

1. Commit any uncommitted changes (use a meaningful commit message).
2. If significant time has passed since you created the branch, use rebase or merge to bring the latest changes from upstream/develop into your branch:
   1. git fetch upstream
   2. git rebase upstream/develop or git merge upstream/develop
   3. Fix any merge conflicts.
   4. Re-test your changes manually, especially if the rebase or merge modified any code related to them.
   5. Re-run the automated tests.
   6. Fix any problems and commit again.
   7. If you are making a PR for a work in progress (WIP) to seek help with your code, it is not necessary for the tests to pass.
   8. If you find it's impossible to run the tests locally due to limitations in your system, it's acceptable to make a PR and then examine the output of the Travis CI build to see if any tests fail. Please write in your PR that you are doing this.
3. Push your commits to your fork of Habitica in GitHub:
   git push origin name-of-your-branch
4. In GitHub, create a pull request (PR) (in brief, go to https://github.com/YourUsername/habitica and click on the "New pull request" button).
   • Give your PR a meaningful title that describes the bug being fixed or the feature being created / modified. It should be possible for people to get some understanding of your PR from the title alone, so it needs to contain more than, for example, "fixes the bug in issue 1234".
   • If your PR will fully fix an issue, add "fixes #[issue number]" to the end of the title (e.g., "fixes #1234").
   • If your PR will partially fix an issue, add "partial fix for #[issue number]" to the end of the title.
   • If you are making a PR to seek help with your code, put "WIP" (Work In Progress) at the start of the title,
   • Follow the instructions that you'll see in the comment field of the PR.
   • If your PR will fully or partially fix an issue, add "fixes #[issue number]" or "partial fix for #[issue number]" in the body of the PR (as well as in the title).
   • Always write a meaningful explanation of your change in detail in the body of the PR. Don't rely on the title explaining it fully and please don't expect the admins to understand the PR just by reading your code. The PR description gives the admins the context necessary to understand and approve code more rapidly, and also allows non-technical staff and contributors to determine if your PR is relevant to them.
   • If your change has a visible effect on the website, include screenshots showing the existing and new behavior to help demonstrate what is changing. To learn how to add images, see the note at the bottom of GitHub's comment field.
   • 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.
   • If you are making a PR to seek help with your code, include the above information and also state that the PR is not complete and describe the help you need.
5. 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. If failures are from your code, admins will ask you to fix the problems before they test and review your code.

A code coverage assessment is also run automatically against your pull request. In theory it is to show whether the automatic tests are sufficient to cover all the new code however its results aren't always meaningful. It's not uncommon to see "coverage/coveralls — Coverage decreased" in the check section of a pull request. If you see this in yours, don't worry about it. If Habitica's admins think that more tests are needed, they'll tell you that in a comment in your PR.

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 will try to do this promptly but the timeframe depends to some extent on how many PRs there are and other factors. PRs for bug fixes will usually be reviewed first because those are highest priority. Other PRs will usually be reviewed in the order that they were received, though sometimes a high priority PR might skip ahead.

Admins might request changes and will then apply the status: pr: with author: needs work GitHub label to your pull request. When that happens, 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 by GitHub's "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 might be optional, depending on the suggestion, but experienced contributors often make good suggestions. If you notice that 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 recommended that you do implement the suggestion or explain why you think it should not be implemented.

If you don't understand the changes requested or are having trouble with them, don't be afraid to ask for help! You are also welcome to commit and push partial changes if you need advice about how to finish them.

If other PRs are merged to develop while yours is being reviewed, admins might ask you to fix merge conflicts. This can be done in your local install by merging in the latest version of upstream/develop and manually editing the conflicts that git tells you about. You are welcome to ask for advice about this if needed!

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. Admins will then replace the status: pr: with author: needs work label with the status: pr: ready for review GitHub label and your PR will go back into the queue for further review.

If you have handled all feedback given to you and your PR has the status: pr: with author: needs work label after a week, please post a small reminder to the PR that you've made the requested changes and that it's ready for review again.

If your PR has the status: pr: with author: needs work label and you haven't made any updates or comments for a month, admins will ask you about your progress. You will have a week to respond to confirm that you’re still working on the PR or your claim on the PR and any associated issue will lapse. You’ll be able to refresh a claim three times before it will lapse automatically. Once your claim has lapsed, admins will either take over the PR to complete it themselves or will release it to the developer community for someone else to work on. If you completed some work that is later merged, you’ll receive partial contributor credit. Admins might shorten these turnaround times if the PR is of high priority - they will clearly state a due date in those cases.

Some of this information was initially released by SabreCat in the PR Process Update blog post.

Making Changes to your PR

To change code that has already been submitted in a PR or to merge in upstream/develop to fix conflicts:

1. In your local install, go to the branch that you created for your change:
   git checkout name-of-your-branch
2. Make the code changes or do the merge and fix any merge conflicts (see above for more details about merging).
3. Commit the changes, using a meaningful commit message (e.g., describe the fixes that were made in response to feedback). If you are just merging you might find that no new commit is needed.
4. Push to your fork of Habitica in GitHub using the same command you used for the original push:
   git push origin name-of-your-branch
   That will automatically update your PR.
   • If you have rebased since the last time you pushed, you might find that a normal push command fails and that you need to do a forced push by specifying -f:
     git push -f origin name-of-your-branch
   • Note that as a general rule you should be cautious about using -f to force any git command to succeed. It's expected and generally necessary when pushing after a rebase, however in any other situation make sure that you understand the consequences of using -f before you use it.
5. When you have finished making changes and pushing, add a comment to the PR to say what has changed and to state that it is ready for review again.

Note that admins will receive emails for all new comments added to PRs, but they are not emailed when any existing comment is edited so to ensure everything you write is seen by admins, make new comments instead of editing old ones. If there is a reason to edit an old comment, you can do that but please also create a new comment to explain what has changed in the previous comment.

Reviewing Other Contributors PRs

Habitica welcomes members of the coding community to review each others’ work and add comments or suggestions on PRs. However please only review if you have a good understanding of the code and have experience with the functional area covered by the PR.

Habitica's staff are considering the possibility of having a new contributor title for users who are doing a particularly good job with reviewing and testing PRs. More information will be given later if this proceeds.

This information was initially released by SabreCat in the PR Process Update blog post.

Принятие пул-реквеста и цикл релиза

When an admin decides that your pull request (PR) is ready to be accepted, they will give it the status: pr: tested and approved; merge pending GitHub label.

Each week by the end of Monday in USA time, admins do a final brief review of all PRs with that label. In rare cases, they will decide to delay a PR for longer (e.g., for more testing on a dedicated test server). Each other PR with that label is merged into the develop branch and a comment is added to 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. Admins really do want to know when they have forgotten this important step! 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.

Once your PR is merged into develop, your change becomes available on a staging server that staff and moderators use for as much of their normal use of Habitica as possible. This means that most new features and bug fixes are used under real-world conditions by several people for a few days before becoming available to all Habiticans. This helps to identify any errors that might have been missed during testing (e.g., if other PRs have negative interactions with your PR). The staging area is not available to other Habiticans.

Each Thursday morning in USA time, admins will migrate all changes that are 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.

Occasionally there will be a week when PRs are not merged on Mondays or deployed to production on Thursdays, for example, during a holiday period when several staff might be on holidays.