How to Contribute

Contributing to Semester.ly follows the following simple workflow:

Create a Branch

Make sure you have followed all of the instructions in Installation to set up your local repository and upstream remote.

We follow the Gitflow workflow; our main branch is prod, and our develop branch is develop. The general gist is that for anything new, you want to branch off of develop and name your branch feature/your-branch-name. Two other conventions we have is for bug fixes we use fix/your-branch-name, and for refactoring we use refactor/your-branch-name. In the case you need to fix something that was just released, and it needs to go straight to production, then branch off of prod and name your branch hotfix/your-branch-name.

To stay up to date with upstream/develop, you’ll want to git pull whenever you’re starting a new branch. You may need to git fetch upstream first.

git checkout develop
git pull upstream develop

Then, you’ll want to create a new branch.

git checkout -b <your-branch-name>

Make Changes

After you’ve made edits, git add your files, then commit. One way to do this:

git add <path_to_file>
git commit -m "Topic: Message"
git push --set-upstream origin your-branch-name

Note

It is preferred that you follow the commit message convention of “Topic: Message”. This helps when we are browsing through commits so we can quickly identify what each commit was about. Messages should be in the imperative mood, as if you’re telling someone what to do. If it helps, you are encouraged to include the how/why - “Evaluation list: Duplicate state to avoid modifying redux state”. Furthermore, try to keep commits to “one” change at a time and commit often.

From here, you should be prompted to create a new pull request (PR). Ctrl + Left Click to open the link. From there, add a short description on what your PR does and how/why you did it, and then create the PR. If your PR is ready for review, add a reviewer as well.

Note

What If Upstream Has Changed? If merging upstream into your branch does not cause any conflicts, using rebase is a good option.

git pull --rebase upstream develop
git push origin your-branch-name

However, if there are merge conflicts, I suggest creating an alternate branch off of your branch and then merging upstream, fixing any conflicts, and then merging back into your branch. Although more complicated, this saves you from messing up the work on your branch if the merge conflicts aren’t easily resolved, or you make a mistake while resolving the conflicts.

git checkout develop
git pull upstream
git checkout your-branch-name
git checkout -b merge-develop
git merge develop
(Fix merge conflicts, git add + git commit)
git checkout your-branch-name
git merge merge-develop
git push

Clean Up Changes

We have GitHub workflows that check your changes and run them against our automated tests. While the workflow is building, we have a few other workflows that check the style and formatting of your code, and they will run more quickly than the build flows. Take this time to fix any formatting or linting issues should these tests fail. Refer to the Style Guide to learn more about our code guidelines.

Note

A PR must pass a few checks before it can be merged.

LGTM: Before your PR is merged, you’ll need to pass a peer review to ensure that all the changes are clean and high quality. Usually, you’ll get an “LGTM” or a few minor edits will be requested. This helps us maintain a quality code base and helps contributors learn and grow as engineers!

PR Body: Your pull request should reference a git issue if a related issue has been created. Additionally, it must provide an in depth description of why the changes were made, what they do, and how they do it.

Tests & Builds Pass: All tests and builds, as run by Github Actions, must pass.

Linting Satisfied: All files must successfully pass our code style checks.

npx prettier "**/*.{js,jsx,ts,tsx}" --write
eslint . --ext .js,.jsx,.ts,.tsx --fix
black .