Thank you for contributing to Predictive Text Studio!
Whether it's a bug report, updated documentation, fixing a typo, or even adding a new feature, we appreciate your contribution.
Above all else, your behaviour is expected to abide by our code of conduct! Be kind.
The following is a guide on how to make code contributions to this project.
- How the branches work
- Setting up your development environment
- Coding Conventions
- For CANOSP Participants
The default branch is called production. Any code here is automatically tested, built, and deployed on the website (currently, https://predictivetext.studio/).
Do not make changes directly to production!
Instead, make a branch, and then make a pull request. Somebody will have a look at your changes, and, upon approval, will merge them into production.
If you are contributing code, follow these instructions to setup the repository on your computer:
You will need:
After cloning this repository, you can install the rest of the dependencies using:
yarn install
Run this to build all the files
yarn run build
In order to test the Google Sheets functionality, you will need to create your own local API keys and save them into your own .env
file.
Perform the following steps:
- Go to https://developers.google.com/sheets/api/quickstart/js to get your API key and client ID
- Copy the
.env.template
file, replace the placeholder values with the ones you obtained above, and save it as.env
To start development, run the following:
yarn run dev
This does a few things:
- Starts
rollup
in "watch mode" - Does an initial build of all of the JavaScript
- Starts LiveReload (you need to install the LiveReload extension for your browser for this to work).
Once the first build has finished, you will be able to see the website at http://localhost:5000/.
With the server running as above (with yarn start
), run this to open
Cypress:
yarn run cy
You can also run unit tests under /test
:
yarn test
In order to test Google Sheets API integration workflow, you will need test/fixtures/credentials.json
and test/fixtures/token.json
.
credentials.json
{
"client_secret": YOUR_CLIENT_SECRET,
"client_id": YOUR_CLIENT_ID,
"redirect_uri": "http://localhost:5000"
}
token.json
: run yarn test
to get the authentication URL e.g. ``. You need to authenticate yourself to get the code. Once you have the code,
access tokens can be obtained by running below command:
curl \
--request POST \
--data "code=<YOUR_CODE>&client_id=<YOUR_CLIENT_ID>&client_secret=<YOUR_CLIENT_SECRET>&redirect_uri=http://localhost:5000&grant_type=authorization_code" \
https://accounts.google.com/o/oauth2/token
You will need to replace code
, client_id
, and client_secret
. The response should follow the below template:
{
"access_token": YOUR_ACCESS_TOKEN,
"expires_in": YOUR_EXPIRES_IN,
"refresh_token": YOUR_REFRESH_TOKEN,
"scope": "https://www.googleapis.com/auth/spreadsheets.readonly",
"token_type": "Bearer"
}
which should be saved as token.json
.
Please make sure your PRs follow our conventions document. Following this guide will prevent many unnecessary PR comments!
CANOSP participants are expected to follow this process in order to contribute to the project:
- Choose a card from the To Do column of the Task board
- Assign yourself to the issue associated with the card
- Create a new branch that addresses the issue in the selected card
- Resolve the issue!
- Create a pull request that resolves the issue
- Inform the team on Slack!
Choose what you're going to work on next!
Go to the Tasks project board and take a look at the To do column.
Choose an issue near the top of the To do column that you're ready to tackle next.
Take the selected card and drag it into the In progress column. Then click the issue title, and find its Assignees. It should say "No one—assign yourself". In this case, click on assign yourself. Now you are on the hook for completing this issue ;)
Note: this section assumes you are using
git
version 2.23 or newer
On your local copy, make sure you're up-to-date with the current version of production:
git switch production
git pull
Then, create a new branch with a name descriptive of the issue you are going to resolve.
git switch --create NAME-OF-YOUR-NEW-BRANCH
Try to name the branch something indicative of what it will attempt to resolve!
Optional: delete your old branch. If you were working on something previously and that branch has already been merged, I would delete that old, merged branch:
git branch --delete NAME-OF-YOUR-OLD-BRANCH
I will use the following prefixes for my branch names, and I suggest you do the same:
docs/
— adds or modifies documentationfeat/
— implements a new featurefix/
— fixes a bugbuild/
— changes topackage.json
,tsconfig.json
,rollup.config.js
, etc.change/
— anything else!
Next, do whatever you need to do to resolve the issue! Here are some guidelines of the tasks you should be doing in certain scenarios:
- Write a test that replicates the bug that you're trying to solve. This isn't always simple to do, so if creating a regression test is taking way too much effort, it's okay to skip this step. However, it is strongly encouraged!
- Find what's causing the bug! Use a debugger, or ask me on Slack about what debugging techniques to use. If you're stuck, discuss the issue in our Slack, and I'm sure you'll figure it out in no time :)
- Fix the bug. Make your fix and commit it. If you've written a new test, make sure your fix passes the test!
- Add a unit test or an end-to-end test or both! It doesn't matter if you do this before or after you write the implementation, but I like to write the test before (test-driven development) if the test is easy enough to write!
- Implement the feature! Make sure the test you wrote passes! Just try to make the code work; don't worry about making it perfect.
- Once the feature works (all of its tests pass), improve it! You may refactor to make the code prettier, easier to read, or easier to change. Or you may make the code faster or reduce its memory requirement. Either way, improvements should be done AFTER the basics of the feature are done!
Note: if you want to be REALLY awesome, create a draft pull request even before your changes are ready. This helps us keep up-to-date with your latest developments, and helps the rest of team out!
Once you're happy with your changes, create a pull request. Push your changes to the main repository.
PROTIP: this command will ALWAYS† setup your branch properly on the first push:
git push -u origin HEAD
†as long as your remote is called origin
!
Typically, your first git push
will print a link from GitHub that you can click
to create a new pull request.
Now write an informative message about your changes. Make sure it references which issue it will resolve!
PROTIP: use a keyword such as resolves, fixes, or closes to automatically close the issue as soon as the PR is merged!
Make a post on the #predictive-text-studio
channel on the CANOSP
Slack! Link to your PR, maybe write a witty comment, and wait for your
PR to be reviewed!