04 Contributing

How to contribute

Welcome to this Beginner-friendly instructional guide for individual contributors and team members working on the Together project!

Table of contents

1. How to get involved
2. Prequisites
3. Together GitFlow structure
4. Finding issues to work on
5. Editing code and submitting a pull request

How to get involved

Guess what! If you are already a member of 100Devs, one of us can personally walk you through all the steps you will need to contribute code to this project. Please send a message on Discord in the Together discussion thread (external link). We will help you no matter what stage of learning you are on with whatever we can. We can assist you in looking for an issue to address, and if no issue exists that fits, we will create one. 🤠

Prerequisites

Anyone is welcome to join Together. If you're a beginner, we ask that you review the documents below before joining an issue. The React Scribma Course does not need to be completed, but having a basic understanding of React is heavily recommended.

• Git & GitHub Crash Course
• Completed Microsoft Introduction to Github
• Read the Contributing Documents
• React Scrimba Course

Together GitFlow Structure

This graph approximates the structure of the official repository and some example feature branches.

%% The graph doesn't render in the GitHub mobile app or in code editors.
%% Enjoy this ASCII art instead.
%%
%%               MVP              v1.0
%% main        o--o------------o---o
%%                 \          /   /
%%                  |\       /   /
%% a_new_feature    | o--o--o   /
%%                  \          /
%% another_feature   o--o--o--o
%%
%%{init: { 'logLevel': 'debug', 'theme': 'default' , 'themeVariables': {
              'commitLabelColor': '#ff0000',
              'commitLabelBackground': '#00ff00',
              'tagLabelFontSize': '16px'
       } } }%%
gitGraph
  commit tag: "MVP"
  commit
  branch a_new_feature
  branch another_feature
  commit
  checkout a_new_feature
  commit
  commit
  checkout another_feature
  checkout main
  merge a_new_feature
  checkout another_feature
  commit
  checkout main
  merge another_feature
  commit tag: "v1.0"

Loading

💡 (Don't be intimidated by this graph. It also confuses most of us.)

We are currently using a GitHub-flow. GitHub-flow allows the production server to remain online and stable as contributors work on adding features and fixing bugs.

The main branch is for stable production code. This branch is the working version and the main branch of the Together app.

Multiple feature branches can be checked out from the main branch. These feature branches are tied to various issues and are used to add new code. When ready, The feature branches are tested and merged into the main branch.

Issues

Together's progress and milestones are split into separate, distinct issues. You are encouraged to request issues you feel will present you with a moderate challenge or that you have a strong interest in. Contributors can request assignments for each issue they wish to work on, and multiple contributors may be assigned to single issues.

💡 Issues tagged with Good 100Devs First Try are beginner-level issues that are great for fellow 100Devs.

There are two ways to discover issues.

Issues Tab

The Issues tab contains all of the issues that are currently in progress, planned to be worked on, or need further review.

Projects Tab

A project management board also exists for this project on GitHub. The project management board contains relevant issues to advance the project to the next milestone or release.

Issues will also be created for any bugs discovered in the project. (Minor fixes and typos do not typically require an issue and can be corrected directly in a pull request with a detailed description.)

Editing code and submitting a pull request

Use the following process to make changes after an issue has been assigned to you.

Forking, cloning, editing, pushing.

Forking

1. Navigate to the Together Project.
2. Click Fork. Difference between forking and cloning a repo
3. Click Create fork.
   

💡 Your new fork will include the main branch as the default branch.

Cloning your fork

Now that you have a personal fork of the project on GitHub, you will be able to clone the fork to your computer. These instructions will cover cloning using the HTTPS Personal access token method.

1. On GitHub, navigate to your fork of the Together repository.

2. Above the list of files, click Code.
   

3. Click the clipboard icon to copy the URL for the repository.
   

4. Open a terminal on your system.

5. Navigate to the directory where you want to clone the files.

6. Type git clone, and then paste the URL you copied earlier. It will look like this, with your GitHub username instead of YOUR-USERNAME:

$ git clone https://github.com/YOUR-USERNAME/Together

7. Press Enter. A clone will be created on your local computer.

Branching

Now that you have the copy, you will need access to the feature branch related to your issue to create a local working branch to write your code.

1. Set upstream to track the remote repository containing the original repo. (Not just your fork.)
   git remote add upstream https://github.com/Caleb-Cohen/Together.git

2. Use this command to fetch the list of remote branches.
   git fetch upstream

3. Checkout the feature branch appropriate for the issue you are working on.
   git checkout <branchname>

💡 The error error: pathspec '<branchname>' did not match any file(s) known to git usually means you mistyped the branch name. Try again using auto tab completion to fill out the correct branch name.

You now have the code and are in the correct feature branch, but before making changes to the project, you should create a new unique branch and check it out. This branch will exist on your local machine and be pushed to your fork on GitHub. Later you will be able to create a Pull Request with this branch.

4. Create and checkout a branch for the task you are working on.

   git checkout -b branch-name

   Name your branch using the following conventions based on the type of issue you're working on :

   feature/issue-{issue number} : for issues with the 'enhancement' label bugfix/issue-{issue number} : for issues with the 'bug' label

5. Make any changes, save your work, and make necessary commits.

   git status verify what has changed.

   git add . stage your files.

   git commit -m "fixed a thingy" perform the commit.

6. Execute testing to ensure your code fits code standards and compliance

   npm run lint

   npm run test-frontend or npm dev-frontend-tests*

   *Review Testing Wiki Page for more information on how testing works.

7. Push the changes to your fork on GitHub

   Typing git push will not work by itself but will show you what command you need to enter. An example shorthand of that command is git push -u origin a-descriptive-branch-name Which will push the code from your origin (your local device) to the correct branch upstream (your GitHub fork.)

8. You must head back to GitHub.com to create a pull request.

Pull requests

1. Visit your fork on GitHub, and a new button should appear, allowing you to create the pull request

   

2. Write a description describing the changes you made, then click "Create pull request"

   

💡 You can link your PR back to the issue it addresses by mentioning the issue ID number in the description box. Include a "closing" keyword if your PR completely resolves the issue mentioned GitHub will automatically close the issue upon merging the PR.

3. A maintainer will review and test your changes and suggest edits if neccesary.

💡 If you make your edits in your branch and commit/push, your pull request in github will automatically update to include that commit.

4. Once everything is good your code will be merged. 👍

Syncing your fork on GitHub

Keep your fork up to date after any pull requests are merged by clicking on "Sync fork" on your forked repository. This will help avoid merge conflicts the next time you submit a pull request.