Purpose
This document will take you through the process and guidelines for contributing to a software project. A general workflow for contributing to this a repo is something like: finding a ticket, making a branch, making changes, committing them, pushing them, then making a pull request. This document will take you through that process step by stepEach project may have more specific guidelines that you can discuss with the project lead or your tech lead.
Table of Contents
| Table of Contents | ||||
|---|---|---|---|---|
|
Git
You will need to have a basic understanding of Git to be able to work on thistickets. For an explanation of all the basic concepts of Git, see this presentation by Nick DePatie
Finding a Ticket
Go to the 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.
...
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 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.
Test Always make sure to test your code to the best of your ability and avoid writing overly complex code. Run On FinishLine: run the unit tests using yarn test:setup then yarn test:frontend or yarn test:backend and try to ensure they all pass. Write 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.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.
...
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.
NOTE: If your commits are not properly tagged, we will reject your pull request and you’ll have to move your changes to a new branch with correct commit messages |
|---|
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.
...
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 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.
...
In the sidebar, request review from any interested team members, which will usually include @anthonybernardi, @jamescd18, @RChandler234, or @joshiarnavyour project lead or a tech lead / head of some sort.
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).
...
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 your repository’s GitHub repository issues page (linked is FinishLine’s) and click the "New Issue" button.
...
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.