Software Contributor Guide

Purpose

This document will take you through the process and guidelines for contributing to a software project. A general workflow for contributing to a repo is something like: finding a ticket, making a branch, making changes, committing them, pushing them, then making a pull request. Each project may have more specific guidelines that you can discuss with the project lead or your tech lead.

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 your project’s issue or project board (Here is FinishLine’s project board for example) 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

There are going to be specific steps per each repo for setting up / cleaning your environment. For example on FinishLine, 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.

Always make sure to test your code to the best of your ability and avoid writing overly complex code. On FinishLine: run the unit tests using yarn test:setup then yarn test:frontend or yarn test:backend and ensure they all pass. Firmware still needs testing setup however in general you should write tests for anything new that you write. If you're unsure of what you should test, ask someone.

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 your repository’s PRs page on GitHub (linked is FinishLine’s) 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 your project lead or a tech lead / head of some sort.

Make sure to follow every step in the PR template!

More Things to Know

Creating Issues And Suggesting Features

Navigate to your repository’s GitHub repository issues page (linked is FinishLine’s) 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.