These instructions are for developers and designers who'd like to contribute code or design help to improve the Footsteps app.

Thanks for your interest in improving the Footsteps App! This page explains how to get set up, how to find something to work on, and how to make a code change. If you run into any problems along the way, please file an issue on our issue tracker.

1. Fork & Clone (why?) the repo. Then, go to footsteps-app (cd footsteps-app) and do git remote add upstream https://github.com/fnplus/footsteps-app.git (use [email protected]:fnplus/footsteps-app.git if using SSH) to add a remote called upstream and link it to Footsteps's main repository (this will be used to merge with the latest version on develop, mentioned later on and also to prevent running lint checks on merge commits when you later update your local branch with upstream/master).
   • If your upstream is not set correctly, the lint checks will run on merge commits as well. The way to fix this will be to update the upstream URL by running the following command: git remote set-url upstream https://github.com/fnplus/footsteps-app.git (use [email protected]:fnplus/footsteps-app.git if using SSH)

There are lots of options!

• Want easy projects? Check out our list of "good first issues".
• Want help figuring out what to do? Just ask us on Spectrum, or send an email to [email protected]. We'll try to help!

If an issue hasn't got someone assigned to it, and there's no existing PR for the issue (you can check this by scanning the list of existing PRs), feel free to take it up by assigning yourself to it. You don't need to ask permission to do so. Also, if you need help or advice on an issue, you can contact the corresponding team lead, whose GitHub username you can find in the issue's grey label.

After you've successfully submitted PRs for two issues and merged them to master, we'll add you as a collaborator on the Oppia repository. Please visit this link to accept the invitation to collaborate. We'll also get in touch to suggest suitable longer-term projects based on your interests, but please feel free to email us at [email protected] if you don't receive the email!

1. Before coding anything, choose a descriptive branch name that is lowercase and hyphen-separated, e.g. fuzzy-rules, and create a new branch with this name, starting from 'develop'. (Also, make sure that your branch name doesn't start with release.)

   You can do all this by running:

     git fetch upstream
     git checkout master
     git merge upstream/master
     git checkout -b your-branch-name
   

2. Make commit(s) to your feature branch. Each commit should be self-contained and have a descriptive commit message that helps other developers understand why the changes were made. However, do not write "Fix #ISSUE_NUMBER" (e.g. Fix #99999) in your commit messages, as this will cause Github to close the original issue automatically. You can rename your commit messages using git commit --amend.

   • To actually make the commit and push it to your GitHub fork, run:

       git commit -a -m "{{YOUR COMMIT MESSAGE HERE}}"
       git push origin {{YOUR BRANCH NAME}}
     

     Make sure to do this from the command line (and not GitHub's Desktop client), since this also runs some important pre-submit checks before your code gets uploaded to GitHub. If any of these checks fail, the push will be interrupted. If this happens, fix the issues that the tests tell you about and repeat the instructions above ('commit' and then 'push').

3. When your feature is ready to merge, create a pull request.

   • Go to your fork on GitHub, select your branch from the dropdown menu, and click "pull request". Ensure that the 'base' repository is the main footsteps repo and that the 'base' branch is 'master'. Add a descriptive title explaining the purpose of the PR (e.g. "Fix issue #bugnum: add a warning when the user leaves a page in the middle of an exploration.").

     • If the PR resolves an issue on the issue tracker, the title must start with "Fix #bugnum: ". This will be the case for most PRs.
     • However, if your PR fixes part of a bigger issue (e.g. the first-contributor-issues listed above), please use "Fix part of #bugnum: " instead. Otherwise, GitHub will close the entire issue automatically when your PR is merged.

   • Fill out the PR checklist, ensuring that your PR description includes the issue number (e.g. "This PR fixes issue #bugnum" or "This PR fixes part of issue #bugnum").

   • Click "Create pull request", then immediately check the "Files changed" tab on your PR on GitHub and read it carefully to make sure that the changes are correct (e.g., that you haven't left out important files that should be part of the PR. (If not, please fix this by making additional commits, or by closing this PR and submitting a new one, before requesting a review.) This is a good way to catch obvious errors that would otherwise lead to delays in the review process.

   • Request a review from the issue's "owner" (which can be found in a label on the issue) and also set them as the PR assignee.

   • Leave a top-level comment on your PR saying "@{{reviewer}} PTAL", where {{reviewer}} is the GitHub username of your reviewer. ("PTAL" means "Please take a look".)

   • After a while, check your PR to see whether the Travis checks have passed.

   • Then, wait for your code to get reviewed! While you're doing so, it's totally fine to start work on a new PR if you like. Just make sure to checkout the develop branch and sync to HEAD before you check out a new branch so that each of your feature branches is based on the main trunk.

   • Resolve any merge conflicts that arise. To resolve conflicts between 'new-branch-name' (in your fork) and 'develop' (in the repository), run:

       git checkout new-branch-name
       git fetch upstream
       git merge upstream/develop
       ...[fix the conflicts -- see https://help.github.com/articles/resolving-a-merge-conflict-using-the-command-line]...
       ...[make sure the tests pass before committing]...
       git commit -a
       git push origin new-branch-name
     

   • In the end, the reviewer will merge the pull request.

4. Tidy up! After the PR status has changed to "Merged", delete the feature branch from both your local clone and the GitHub repository:

     git branch -D new-branch-name
     git push origin --delete new-branch-name
   

5. Celebrate. Congratulations, you have contributed to Footsteps!

• Our central development branch is master, which should be clean and ready for release at any time. All changes should be done in feature branches based on master.

• If you face any issues while setting things up, or your PR build fails unexpectedly (please go through the logs of the PR build and try debugging the problem on your own first!), feel free to ping @oppia/dev-workflow-team for help.

• To find the author of a particular change in a file, run this command:

  git blame file-name
  

  The output will show the latest commit SHA, author, date, and time of commit for each line.

  To confine the search of an author between particular lines in a file, you can use:

  git blame -L 40,60 file-name
  

  The output will then show lines 40 to 60 of the particular file.

  For more git blame options, you can visit the git blame documentation.

• If your PR includes changing the location of the file, if you simply move the file by cut and paste method, then the git will track it as a new file. So to prevent this, use:

  git mv old_file_path new_file_path
  

  By using this command git will detect the file as a renamed file.

We have a developer chat room here. Feel free to drop in and say hi!