Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
355 lines (233 loc) · 17.8 KB

CONTRIBUTING.md

File metadata and controls

355 lines (233 loc) · 17.8 KB

How to Contribute to VRMS

First off, thank you for taking the time to contribute! 🥳👍

This document outlines the process for joining our team and contributing to the VRMS Github repository. If you notice errors or have important information to add, please feel free to propose changes to this document with a pull request

Table of Contents

Part 1 : How to join the team

1.1 VRMS contributor expectations

  • Attend at least 1 team meeting per week
  • Devote a minimum of 6 hours per week to working on VRMS assignments
  • Communicate with the team leadership if you plan to step away from the project

1.2 Reach out to us on Slack

If you would like to contribute to our project, please reach out to the team leads on Slack or at one of our weekly meetings. You can find the current project team, their slack links, and our team meeting times on the VRMS Project Details Page.

1.3 Become a member of the repository Team

Send your GitHub name to the project manager, or post it in the VRMS Slack channel, and we'll add you as a member to the GitHub repository Team. Note: you should be added to both the VRMS and VRMS-write teams.

Once you have accepted the GitHub invite (via email or in your GitHub notifications), please do the following:

  1. Mark your own membership public https://help.github.com/en/articles/publicizing-or-hiding-organization-membership#changing-the-visibility-of-your-organization-membership

  2. Setup two factor authentication on your account hackforla/admin-governance#20

These steps are mandatory in order to contribute to all HackforLA projects.

Part 2: How to set up the development environment

2.1 Fork the repository

A fork is a copy of the repository that will be placed on your GitHub account url.

NOTE: This copy is on a remote server on the GitHub website and not on your computer yet.

  • Click the icon again, it will give you the URL associated with your forked repository and not create a new fork.

2.2 Clone the remote repository to your local computer

The following process will make a copy of the fork that you just created on your local computer.

  1. Create a new folder on your local computer that will contain hackforla projects.

  2. In your shell (terminal), navigate to this folder then run the following commands:

    git clone https://github.com/YOUR_GITHUB_USERNAME/vrms.git

    You should now have a new folder in your hackforla folder called vrms.

  3. Verify which URL your origin remote is pointing to:

    git remote show origin

    Your terminal should return:

    remote origin
Fetch URL: https://github.com/YOUR_GITHUB_USERNAME/vrms.git
Push URL: https://github.com/YOUR_GITHUB_USERNAME/vrms.git
...

    If you accidentally cloned the hackforla/vrms.git then you can change your local copy to upload to your fork with the following:

    git remote set-url origin https://github.com/YOUR_GITHUB_USERNAME/vrms.git

  4. Add another remote called vrms that points to the hackforla version of the repository. This will allow you to incorporate changes later:

    git remote add vrms https://github.com/hackforla/vrms.git

Note: Understanding how git remotes work will make collaborating much easier. You can learn more about remotes here and here.

2.3 Get up and running

  1. Install NVM (Node Version Manager). NVM allows you to easily manage and switch between multiple versions of Node.

    • Verify the installation: nvm --version
    • Once NVM is verified, run the following commands from the root of the project:
    # Install the project's Node version (specified in the .nvmrc file)
nvm install

# Instruct NVM to use the Node version defined in the .nvmrc file
nvm use

    NOTE: If the major version of Node does not match the version specified in the .nvmrc file, you may need to be explicit with the version and use: nvm install <version> and nvm use <version>

  2. Have Node and NPM installed locally:

    • Verify with node -v and npm -v respectively.

  3. Install Yarn: an improved package manager

    • Verify with yarn --version

  4. Verify that you have the git remote repositories configured:

    • Verify that the output of git remote -v shows your local repo as origin and the upstream vrms repo.

  5. Install the node packages needed in each directory:

    • cd vrms/ and run yarn install
    • cd client and run yarn install
    • cd ../backend and run yarn install

  6. Add your required environment variables for the frontend and backend directories:

    • touch vrms/backend/.env
    • touch vrms/client/.env

    Note 1: In the above example you are trying to create an empty file called .env in each of the listed directories: backend and client. You can use either touch <path-to-directory> .env or navigate to the directory and use touch .env

    Note 2: touch is a Unix/Linux or Mac command; It is not available in Windows. In Windows, use a text editor (e.g. Notepad) to create an empty file and save it in each of the locations as .env . (If you use Windows Explorer to create the file it will create a file called .env.txt, which will not work.)

    • Then paste the content from the document. It is accessible for the project team members only.

    • Please note that the ports for the frontend and backend are set in this location

  7. Set up Husky for Git hooks (required for all contributors):

    To help enforce code quality and prevent errors from being committed, we use Husky to manage Git hooks. Husky should install itself automatically after you install dependencies (thanks to the prepare script in package.json).

    If you notice that Git hooks are not working (for example, you don't see linting or formatting checks when committing), you may need to set up Husky manually. To do this, run the following in the root of the project:

    npx husky install

    If you encounter issues, see the Husky documentation or reach out on Slack!

  8. Take a second to review the app.js and server.js files in the vrms/backend folder. These two files are a blueprint for the back end, so please familiarize yourself with it. You'll see folders for the database collection models, routes for the API, and a config file which loads the necessary environment variables.

  9. Start the local development servers (frontend & backend).

    To run client:

    • Navigate to the root of the application vrms/ and run yarn start

    Troubleshooting : If you encounter the following error after running yarn start:

    Error: error:0308010C:digital envelope routines::unsupported

    Try changing your node version to 16.14.2 by running nvm use 16.14.2. If you do not have nvm installed, see install instructions

You should now have a live app. Happy hacking.

2.4 Running Tests

The VRMS application has a variety of tests written for the application. Review the package.json file in any directory and look for any variation of test scripts.

To run all of the tests run npm run test:all from the root folder.

2.5 Using the development database

The application uses MongoDB. We have created a shared development database using MongoDB Cloud and MongoDB Atlas. The connection string for the development database is included in the environmental variables that you pasted into your backend/.env file in step 5 of the "Get Up and Running" section. If you completed that step successfully you should not need to do anything else.

To view and edit the development database manually, you can download MongoDB Compass. To connect to the development database you will use the "DATABASE_URL" from the document that contained the environmental variables. The string will start with "mongodb+srv://".

If you want to install a local copy to experiment with and learn more about MongoDB, you can use this tutorial

Part 3: How to work on issues

3.1 Claim an Issue

Developers may assign themselves to issues from the Prioritized Backlog column of the project board.

The Prioritized Backlog column is filtered so the first (top) issue has the highest priority and should be worked on next if possible.

Developers may choose from issues with the following role labels:

  • role: Front End
  • role: Back End
  • role: Database
  • role: devops
  • Lead developers may choose from the above labels, as well as issues with the label: role: Dev Lead

Claiming an issue is a two step process:

  1. Assign yourself to the issue using the gear icon in the upper right corner of the issue where it says "Assignees"
  2. Move the issue from the Prioritized Backlog to the In Progress column of the project board

You may want to consider bookmarking your Github Issues page to track your current tasks: https://github.com/issues/assigned

3.2 Create a new branch for each issue you work on

You will create a new branch for each issue you work on. Doing all your work on feature branches leaves your repository's main branch unmodified and greatly simplifies keeping your fork in sync with the main project.

  1. Before creating a new branch, always make sure you are currently on the development branch by using the command 
    git branch
  2. Before creating a new branch, always pull down the latest changes from the development branch by using the command 
    git pull vrms development
  3. Finally, create a new branch where you will work on your issue by using the command: 
    git checkout -b your-branch-name

3.2.1 Check for and resolve linting/prettier errors before making changes

Before you begin working on any part of a file, always check for existing code errors in the codebase. This helps prevent introducing new issues and ensures a stable foundation for your work.

  • Use your code editor's error checking tools or run the appropriate linting/compilation commands (e.g., yarn lint (filename), or your IDE's error panel) to identify any errors in the files you plan to edit. (This isn't your fault, it's just an old codebase 🤷‍️)
  • If you find errors, resolve them in a separate commit before starting your feature or fix work. Use a clear commit message such as:

fix: Resolve existing linting and compilation errors

(This makes it easier for reviewers to distinguish between error fixes and your new changes.)

  • If you are unsure how to fix an error, ask for help in the team Slack channel or consult the documentation.
  • Only begin implementing new features or fixes after confirming the file is error-free.
  • If you are unable to resolve the errors after making a reasonable effort, it is acceptable to use --no-verify when committing or pushing your changes. Please leave a comment in your pull request explaining why this was necessary.

3.3 Work on the Issue

Every issue will contain action items you must complete before you are ready to submit a pull request. Be sure to use the checkboxes as you complete each action item so we can track your progress!

After you have completed the action items, add and commit the changes to your new branch using the commands

git add .
git commit -m "your commit message"

Part 4: How to create pull requests

4.1 Push changes to your forked repository

  1. Before pushing code, always pull down the latest changes from the development branch by using the command 
    git pull vrms development
  2. Once you are satisfied with your changes, push them to the feature branch you made within your remote repository. 
    git push --set-upstream origin your-branch-name

4.2 Create a pull request on the VRMS repository

  1. Go to your fork of the VRMS repository on GitHub and click on the Compare & pull request button.
    See screenshot
  2. Be sure to title your pull request by summarizing the changes you made
  3. Be sure to add your issue number where the template says Fixes #replace_this_text_with_the_issue_number
  4. Fill out the "What changes did you make and why?" section of the pull request template
  5. Include before & after images with your pull request if there are visual changes to the user interface
  6. Request a review from another developer on the team
  7. Review another developer's pull request while you are waiting for your pull request to be reviewed

Part 5: How to review pull requests

Reviewing pull requests is an important part of maintaining code quality and helping team members improve their contributions. Here’s how to review a pull request on the VRMS repository:

  1. Navigate to the Pull Requests tab
    Go to the Pull Requests section of the repository to see open pull requests.

  2. Select a pull request to review
    Choose a pull request that is ready for review (look for those assigned to you or marked as "Ready for review").

  3. Read the pull request description
    Review the summary, linked issue(s), and any screenshots or documentation provided by the author.

  4. Check the code changes

    • Click on the "Files changed" tab to see the code diff.
    • Look for code quality, readability, and adherence to project conventions.
    • Ensure the code addresses the issue and does not introduce bugs.

  5. Run the code locally (optional but recommended)

    • Pull the branch to your local machine.
    • Follow the setup instructions to test the changes.
    • Run tests to verify nothing is broken.

  6. Leave feedback

    • Use GitHub’s review tools to comment on specific lines or leave general feedback.
    • Be constructive and respectful in your comments.

  7. Approve or request changes

    • If the pull request is ready, click "Approve".
    • If changes are needed, click "Request changes" and specify what needs to be addressed.

  8. Merge the pull request (if authorized)

    • If you have permission and the pull request meets all requirements, you may merge it.
    • Otherwise, notify the author or a maintainer that it is ready to merge.

Tip: You can use the following helpful git alias to quickly check out a pull request locally:

# This git alias allows you to quickly check out a pull request by its number.
# eg "git pr 1820 vrms"
git config alias.pr '!f() { \
  # If no arguments are provided, print usage instructions
  if [ $# -lt 1 ]; then \
    echo "Usage: git pr <id> [<remote>] # assuming <remote>[=origin] is on GitHub"; \
    echo "    eg: git pr 1340 upstream"; \
  else \
    # Save current HEAD (optional, for safety)
    git checkout -q "$(git rev-parse --verify HEAD)" && \
    # Fetch the pull request from the specified remote (default: origin) into a local branch
    git fetch -fv "${2:-origin}" pull/"$1"/head:pr/"$1" && \
    # Check out the fetched PR branch
    git checkout pr/"$1"; \
  fi; \
}; f'

This allows you to run git pr <PR_NUMBER> to fetch and check out a pull request by its number. For example: git pr 1234 upstream.

Resources: