Software Contributor Guide

Purpose

This document will take you through the process and guidelines for contributing to the app. A general workflow for contributing to this repo is something like: finding a ticket, making a branch, making changes, committing them, pushing them, then making a pull request.

Table of Contents

Git

You will need to have a basic understanding of Git to be able to work on tickets. For an explanation of all the basic concepts of Git, see this presentation by Nick DePatie

Finding a Ticket

Go to the project board to see all the tickets that are ready for dev work. You can pick any ticket you’d like that isn’t assigned to anyone. However, be aware that high priority tickets need to be done faster. If you’re new, check out the “straightforward todo tickets” tab to find a good beginner ticket to work on. When you’ve found something you like, check in with your Tech Lead, then assign it to yourself.

Creating a Branch

Before making a new branch, make sure you are on develop and you have the latest changes (git pull).

Then use git checkout -b [branch name] to create and switch to a new branch. Give the branch a short name that follows the naming syntax: #[issue number]-[short but meaningful description] and replace spaces with dashes. Example: #12-add-login-endpoint or #275-refactor-projects-table. The # is important so that GitHub links it to the issue.

Use git status to check which branch you are on. Ensure you stash, reset, or commit your changes before changing branches, unless you want to bring your changes to the other branch. Use git checkout develop to switch back to the develop branch.

Writing Code

Always run yarn install when switching to a new branch. You might even need to run yarn prisma:reset if there have been changes to the schema across branches.

Comment your code with JSDoc and inline comments to help others understand your code. Follow good coding practices taught in Fundies 1 and Fundies 2.

Test your code to the best of your ability and avoid writing overly complex code. Run the unit tests using yarn test:frontend or yarn test:backend and ensure they all pass. Write tests for anything new that you write. If you're unsure of what you should test, ask someone.

If you edit code in any local package (e.g. shared), you may need to run yarn install before the latest changes to the local package will be available in the rest of the application.

Creating a Commit

Commit early and often (within reason) to properly save your work and to make your changes more easily separable.

Use git status to see which files have been changed. If you see yarn.lock in there, run git restore yarn.lock. This file should only be committed if you are adding new packages to the repo.

Next, do git add path/to/file for each file you want to stage to your commit. You can also do git add -A to add all of them, but make sure there are no unwanted files you’re adding first. Run git status again and you should see that your files are properly staged.

Next, use git commit -m [message] to commit your staged file with the message. Use the following syntax for commit messages: #[issue number]: [description of changes made]. Examples: #12: Expanded the creating commmits section or #79: Increased list padding. The # is important so that GitHub can link it to your ticket.

Pushing Commits

Use git push to push your branch and commits to the remote GitHub repo. You may need to run git push --set-upstream origin [branch name] as instructed by the git CLI if the branch does not already exist in the GitHub repo and only exists on your local computer.

Whenever you make a new commit, you’ll need to push it to GitHub again.

Creating a Pull Request

Pull requests (aka PRs) allow for others to review your code before it gets merged together with the develop branch. Don't be afraid to open a PR before you are finished if you want feedback on your code, just make sure to note this in your PR. Pushing more commits to the GitHub repo will add them to the PR.

Navigate to the PRs page on GitHub and click "New pull request". You may have to select the branch which you would like to merge into the develop branch.

Give your PR an informative and concise title. PR titles often match the title of the issue they are linked to, but they do not have to be exact.

Use closing keywords in the description of the PR to link the PR with any associated issue(s). Example: closes #27 will link issue #27 to the PR and close the issue when the PR is merged.

In the sidebar, request review from any interested team members, which will usually include @anthonybernardi and @RChandler234.

Make sure to follow every step in the PR template!

More Things to Know

Running the App Locally

First make sure you have run yarn install and yarn prisma:generate on the branch you want to start. Then use yarn start to boot up the React app and the Express server on your local computer. Navigate to localhost:3000 to see the frontend of the app. The API endpoint can be found at localhost:3001/ (check out localhost:3001/users for example).

When to commit yarn.lock?

yarn.lock contains all the dependencies of the project. Thus, when dependencies are added or removed from the project, or when the version of any dependency is changed, then yarn.lock needs to be committed to the branch and pushed to the remote repository. Unless there are changes to the dependencies in any package.json, you should not commit and push any changes to yarn.lock.

Creating Issues And Suggesting Features

Navigate to the GitHub repository issues page and click the "New Issue" button.

Issue Title

Give your issue an informative, but concise title that follows the naming syntax: [Page] - [Description]. The page field should name one specific page within the application that the issue pertains to. Alternatively, use General or Docs to indicate issues spanning the whole site or issues with the project's documentation. The description field should briefly describe what the issue is. Examples: General - Increase Padding for Tables or Projects - Add Filter by Project Lead.

Issue Description

Include the required information in the issue description given by the template.

Add labels as is appropriate for the issue, and put it in the #software_product channel for review. Reviewers will determine whether the issue is valid, whether it will be accepted and worked on, and which milestone it will be a part of. Once it is approved, it will be added to the project board.