Process for contributing new code

Here's an overview of the process we follow to contribute new code to the sidewalk repo.

develop Branch for Resolving Issues

The production server, projectsidewalk.io, runs the main master branch of the git repo which contains stable code. For adding new features, fixing issues and bugs, we have another branch called develop. When you start to work on an issue, you need to create a branch for your work from the develop branch (since it has the latest code).

Issue Branch Naming Conventions

To name your branch, follow this convention:

<git-issue-no>-<main category>-issue-description

E.g. You are implementing a fix for this issue: https://github.com/ProjectSidewalk/SidewalkWebpage/issues/474

So the name of the branch would be: 474-admin-update-activities-table

Here, 'admin' is the main category. More examples could be 'landing-page', 'faq', 'onboarding' etc. For some issues, there might not be a category. In those cases, just omit that part from the branch name.

This nomenclature helps to automatically add a label 'work-in-progress' to the issue you are working on when you publish the branch to the repo and provides a good descriptive branch name.

Testing your Contribution

To test out changes that will affect different users in different ways, you should test your code locally.

1. To login as a normal user: Simply create an account and login via the "Sign in" button in the top right of the page.
2. To login as a mechanical turk user, visit localhost:9000/?referrer=mturk&hitId=h1&workerId=worker1&assignmentId=a1&minutes=60 instead of localhost:9000.
3. To login as a researcher/admin, you have to manually change your role id. To do this, open the user_role table in the database, and change the role_id corresponding to your user_id to 3 (Researcher) or 4 (Administrator). These IDs are defined in the role table.
   • To find your user_id, you can search through the recent webpage_activity table entries
4. To run the mocha tests, enter the public/javascripts/SVLabel/spec directory, find the respective <module-name>SpecRunner.html file (e.g. RibbonSpecRunner.html for the ribbon module) in the directory named after the module that you changed and open it in your preferred browser. This should bring up an html page outlining the results for the mocha tests for that specific js module. Furthermore, there is a SpecRunner.html file in the public/javascripts/SVLabel/spec directory which runs all mocha spec tests.

Submitting PRs

Finally, when you submit a pull-request that will be reviewed before we merge it with develop branch (and consequently to master branch), write descriptive titles and include the issue number (e.g. #408: <PR Title>) in the title. Finally, in the pull request description, mention the following things:

1. "Resolves/Fixes <#issue-number>": Write either the words "Resolves" or "Fixes" along with the issue/bug number. It needs to be added when you create the PR. This will automatically add the "pull-request-submitted" label to the issue you are working on and to the pull request. For an example, see this PR.
2. Add a brief description of the main changes you made and if it would have any side-effects to other parts of the application. Again, refer to the previous example for reference. Additionally, it is always nice if you give instructions to other users on how to test your changes.

The automatic labeling ('work-in-progress' or 'pull-request-submitted') is done by waffebot that we use for managing issues. Hence, the requirements. Ask before closing an issue associated with a pull-request. The protocol is to test the fix on both the issue branch and develop before closing the issue.

Things to keep in mind:

1. Keep the PR small - only related to the issue in hand. Don't try to solve too many issues in one PR.
2. Before submitting PRs for UI related issues, provide a before and after screenshot in the issue thread first. The team will provide their comments and we will come to a conclusion there. Then submit the PR. The PR thread should be reserved for all comments related to the implementation and things that come during testing.