Process for contributing new code - ProjectSidewalk/SidewalkWebpage GitHub Wiki
Here's an overview of the process we follow to contribute new code to the sidewalk repo. As you write code, also make sure to follow our style guide. This is broadly the process that you will follow when you're ready to write code for a new ticket while using git through the command line (though you can do the same things through Github Desktop):
$ git checkout develop // always make sure to branch off of develop
$ git pull // make sure you have the most recent code from the repo
$ git checkout -b <branch-name> // see branch naming convention section below
$ git push --set-upstream origin <branch-name> // push your branch to Github for the first time
$ // write some code
$ git status // see what you changed; ignore changes to docker-compose.yml and .ivy2/ files
$ git diff <filename> // use on each file you edit to ensure you don't commit something accidentally
$ git add <filename> // if the changes look good, git add "stages" the file for commit
$ git commit -m "descriptive message" // commit the changes to the files you staged to your local branch
$ git push // push your changes to Github!
One problem that it may be worth mentioning at the top here: When you're ready to commit changes to your code, do not commit everything at once with git commit .
or git commit -a
. Use git status
to see which files have been edited, then use git diff <path-to-file>
on each file to make sure that the only changes there are changes you intended to make. Then you can use git add <path-to-file>
to add that file for committing. This helps to avoid a common issue of committing code that you had just added for testing purposes.
In addition, before creating a PR (as well as before you ask for another review after making changes to a PR), pull the most recent changes from the develop branch into your branch using git pull origin develop
. You should then test again using this most recent code from the develop branch to make sure that your changes still work!
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). This is why you start with git checkout develop
before running git checkout -b <branch-name>
.
To name your branch, follow this convention:
<git-issue-no>-<brief-description>
E.g. if you are implementing a fix for this issue: https://github.com/ProjectSidewalk/SidewalkWebpage/issues/474, you might name your branch474-admin-update-activities-table
. Please refrain from including the '#' sign at the beginning of the branch name, because that can mess up command line autocomplete :)
- When trying to count the number of rows when using Scala's Slick library, you should use
.size.result
NOT.length.result
. The former just does aCOUNT(*)
, while the latter loads all data into memory before counting. - If you're writing code that is very computationally intensive in Scala, you should use the
cpu-intensive
ExecutionContext rather than the default one. There are a few examples of this throughout the code. Note that you don't need to use this for queries on the db (but you my want to if you're processing the data in Scala after). And if you're using aMaterializer
, which I believe that streaming from the db does, it will use thecpu-intensive
context by default, so there's nothing extra that you need to do there. You can ask Mikey if you have questions here.
If so, then you will need to add in temporary translations into Spanish, Dutch, German, and Mandarin (traditional, not simplified). You can use Google Translate for this. Mikey will compile a list of all the temporary translations that we make using Google Translate and will occasionally send that list to our partners that provide official translations. Below is how to add new translations:
- If you are adding text in a
.scala.html
file, add a line to each of theconf/messages.en/es/nl/zh
files with the translations, and reference those in the HTML file using@Messages("your.translation.id")
. - If you are adding text in a JavaScript file, add the translations to the appropriate files in
public/locales
and reference them in the JavaScript usingi18next.t('your-translation-id')
.
If you are removing text that is being translated, then you should first check if the translated text is being used anywhere else on the website. If it is not, then you should remove those translations in every language.
And finally, we are also supporting a couple regional English dialects, namely US (en-US) and New Zealand (en-NZ). By default, you should just add your text to the generic "en" files. But for any words/phrases that are unique to the US or NZ, you should also add a translation to the en-US and/or en-NZ files. Below are the list of changes.
- For en-US
- For any mentions of distance, the generic "en" files should use meters/m/kilometers/km, and the en-US versions should use feet/ft/miles/mi. Your code should take this into account as well, and you should be able to find examples of this throughout our code.
- For en-NZ, the changes should be simple
- curb ramp -> drop kerb
- sidewalk -> footpath
- crosswalk -> pedestrian crossing
- neighborhood -> neighbourhood
- meter/meters/kilometer/kilometers -> metre/metres/kilometre/kilometres
- organization -> organisation
- trash/recycling can -> trash/recycling bin
If so, you will want to test on mobile as well; our mobile site shows only the Validate and sign in/up pages Here is how to test out the mobile website:
- Start by testing using Google Chrome's dev tools. You can see some quick instructions for how to open those here.
- If things look good in Chrome's dev tools, you should then test on your own mobile device if possible (the emulator is far from perfect). To test on your mobile device, find you IP address using
ipconfig
orifconfig
in your terminal. Then go to<ip_address>:9000
on your mobile device instead oflocalhost:9000
. Some caveats:- Your computer and phone need to be on the same wifi network for this to work
- This often doesn't work at coffee shops and the like. Presumably they have some security measures in place to prevent this.
- Tools like
ipconfig
andifconfig
can sometimes show you multiple different IP addresses. Make sure to try all of them to find the right one!
If so, you can create an admin account in your local dev environment relatively easily by changing the "role" for an account in the database to "Administrator". Steps below:
- Create an account on your local environment if you haven't already.
- Open your database in a database manager like Valentina Studio (instructions on that here). Or you can work fully command line by running
make ssh target=db
in the root project directory, followed bypsql -d sidewalk -U <database_user>
(same user as in yourdocker-compose.yml
). - Find your
user_id
in the database. You can do this visually by looking at entries in thesidewalk_user
table in thesidewalk_login
schema, or by running the querySELECT user_id FROM sidewalk_login.sidewalk_user WHERE username = '<your-username>';
. - Update your role in the
sidewalk_login.user_role
table from 1 (Registered) to 4 (Administrator). Again, you can do this visually by looking through theuser_role
table and updating the entry, or by running the queryUPDATE sidewalk_login.user_role SET role_id = 4 WHERE user_id = '<your-user-id>';
.
If so, you should test the site for those different types of users! Instructions on how log in as each type of user below:
- Anonymous user: You are given an anon account by default when visiting the site for the first time. The easiest way to test like this is to open a new incognito/private browser window, which should give you a fresh anon account (you should see the "Sign in" button in the navbar, not a username).
- Registered user: Simply create an account and login via the "Sign in" button in the top right of the page.
- Administrator: Instructions in the section above this one!
- Amazon Mechanical ("MTurk") Turk user ("Turker"): To login as a mechanical turk user, visit
localhost:9000/?referrer=mturk&hitId=h1&workerId=worker1&assignmentId=a1&minutes=60
instead oflocalhost:9000
. If the session you made for that user times out, you can just change theworkerId
,hitId
, andassignmentId
in the URL to start an account for a new turker. If you want another session with the same user, just change thehitId
andassignmentId
.
- The last thing to do before creating a PR is to pull the most recent changes from on the develop branch into your own branch using
git pull origin develop
. Then test your changes one last time using this updated code. - Next, you should run the Scalafmt formatter on any Scala files that you edited. The keyboard shorcut in IntelliJ is
ctrl-alt-L
, and there's a similar one for VS Code. I believe that it can be set up to run the formatter whenenver you save the file as well if you like. - Push the merge commit and your formatting commits to your branch on Github, then create the PR.
- Submit a pull request here. The left-hand side should be
develop
, since that is the branch we want to merge into, and on the right-hand side you should select the branch your changes are on. Write descriptive titles and follow the provided template. - Your PR will be reviewed (most likely by Mikey) before we merge it into the
develop
branch (and eventually themaster
branch). After your PR is reviewed, make the necessary changes and then post a final comment on the PR to let us know that you've finished fixing everything so that we can review it again!
Things to keep in mind:
- Make sure that your code adheres to our style guide before requesting a PR review!
- Keep the PR small - only related to the issue in hand. Don't try to solve too many issues in one PR.
- 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.