-
Notifications
You must be signed in to change notification settings - Fork 22
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add contributing guide for developers (#119)
- Loading branch information
1 parent
5e5bde5
commit cb18793
Showing
1 changed file
with
183 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,183 @@ | ||
| # MERL Center Developer Guide | ||
|
|
||
| ### Table of Contents | ||
| 1. [Set Up Local Dev Environment](#set-up-local-dev-environment) | ||
|
|
||
| 2. [Review A Pull Request](#review-a-pull-request) | ||
|
|
||
| 3. [Create A Pull Request](#create-a-pull-request) | ||
|
|
||
| ##### *For this guide, please replace text surrounded by `<>` with the appropriate text for each command. Do not include `<>` characters in your commands. | ||
|
|
||
| ## Set Up Local Dev Environment | ||
|
|
||
| #### 1. Check if you have git installed with the command below. | ||
| ``` | ||
| git --version | ||
| ``` | ||
| If you do not have git on your machine, follow the installation instructions [here](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) | ||
| #### 2. Fork your own copy of merl-center-public repository on GitHub by clicking the fork button in the top right corner of the repository page | ||
|
|
||
| <details><summary><b>see screenshot</b></summary> | ||
|
|
||
|  | ||
|
|
||
| </details> | ||
|
|
||
| #### 3. Clone your forked repository | ||
| ``` | ||
| git clone <your-fork-url>.git | ||
| ``` | ||
|
|
||
| <details><summary><b>see screenshot</b></summary> | ||
|
|
||
|  | ||
| </details> | ||
|
|
||
| #### 4. Navigate into root directory of repository you just cloned | ||
| ``` | ||
| cd MERL-Center-public | ||
| ``` | ||
| #### 5. You have two options for starting the server locally | ||
| #### Option #1 - Using Docker (recommended) | ||
| ##### 1a. Check if you have Docker installed locally. If you don't have Docker installed, follow the instructions [here](https://docs.docker.com/get-docker/) | ||
|
|
||
| ``` | ||
| docker -v | ||
| ``` | ||
| ##### 1b. Run this command to build the Docker image | ||
|
|
||
| ``` | ||
| docker compose build | ||
| ``` | ||
| ##### 1c. Run this command to start the server locally | ||
| ``` | ||
| docker compose up | ||
| ``` | ||
|
|
||
| #### Option #2 - Using Ruby directly | ||
| ##### 2a. Check if you have Ruby installed locally. If you don't have Ruby installed, follow the instructions [here](https://www.ruby-lang.org/en/documentation/installation/) to install Ruby | ||
| ``` | ||
| ruby -v | ||
| ``` | ||
| ##### 2b. Install the bundler gem with this command | ||
| ``` | ||
| gem install bundler | ||
| ``` | ||
| ##### 2c. Install dependencies from Gemfile with this command | ||
| ``` | ||
| bundle install | ||
| ``` | ||
| ##### 2d. Run this command to start the server locally | ||
| ``` | ||
| bundle exec jekyll serve --livereload | ||
| ``` | ||
|
|
||
| #### 6. Navigate to `localhost:4000` in your browser to see the site running locally | ||
|
|
||
| #### 7. Add a remote called `upstream` to your local repository that points to the main repository | ||
| ``` | ||
| git remote add upstream https://github.com/MERLTech/MERL-Center-public.git | ||
| ``` | ||
| Verify that the origin remote points to your fork and the upstream remote points to the main repository | ||
| ``` | ||
| git remote -v | ||
| ``` | ||
|  | ||
|
|
||
| #### 8. Add fetch configuration to simplify pulling down branch data for pull request reviews | ||
| ``` | ||
| git config --add remote.upstream.fetch "+refs/pull/*/head:refs/remotes/upstream/pr/*" | ||
| ``` | ||
| This command adds additional fetch instructions to your `.git/config` file so that you can more easily pull down branches from pull requests on the upstream repository | ||
|
|
||
|
|
||
| ## Review A Pull Request | ||
| #### 1. Add yourself as a reviewer of the pull request on Github | ||
| <details><summary><b>see screenshot</b></summary> | ||
|
|
||
|  | ||
|
|
||
| </details> | ||
|
|
||
| #### 2. Make sure you are on the main branch of your local repository | ||
| ``` | ||
| git switch main | ||
| ``` | ||
| #### 3. Pull down latest changes from main branch of upstream repository | ||
| ``` | ||
| git pull upstream main | ||
| ``` | ||
| #### 4. Fetch all pull request data from the main repository using the upstream remote that was modified in step 8 of setting up your local dev environment | ||
| ``` | ||
| git fetch upstream | ||
| ``` | ||
| #### 5. Checkout the specific pull request you want to review | ||
| ``` | ||
| git checkout upstream/pr/<number> | ||
| ``` | ||
|
|
||
| #### 6. Run the start script from our package.json | ||
| ``` | ||
| npm run start | ||
| ``` | ||
| #### 7. Navigate to `localhost:4000` in your browser to check if the changes from the pull request are working as expected | ||
|
|
||
| #### 8. Go back to github and find the "Files Changed" tab of the pull request to submit feedback | ||
| <details><summary><b>see screenshot</b></summary> | ||
|
|
||
|  | ||
|
|
||
| </details> | ||
|
|
||
| You have three options for submitting feedback: | ||
| <br> | ||
| - Leave a comment on the pull request | ||
| - Approve the pull request which will allow for merging | ||
| - Request changes which will prevent pull request from being merged until changes are made and you re-review the pull request | ||
|
|
||
|
|
||
|
|
||
| ## Create A Pull Request | ||
| #### 1. Switch to the main branch | ||
| ``` | ||
| git switch main | ||
| ``` | ||
| #### 2. Pull down latest changes from main branch of upstream repository | ||
| ``` | ||
| git pull upstream main | ||
| ``` | ||
|
|
||
| #### 3. Create a new branch for each issue you work on | ||
| ``` | ||
| git checkout -b <relevant-branch-name> | ||
| ``` | ||
|
|
||
| #### 4. Verify that you are on your newly created branch from step 3 and NOT on the main branch | ||
| ``` | ||
| git branch | ||
| ``` | ||
|
|
||
| #### 5. Make necessary changes to code in order to satisfy the requirements of the issue you are working on | ||
|
|
||
| #### 6. Add the changes to staging area | ||
| ``` | ||
| git add . | ||
| ``` | ||
| #### 7. Commit the changes to your local repository | ||
| ``` | ||
| git commit -m "short descriptive commit message" | ||
| ``` | ||
| #### 8. Push the changes to your forked repository using the `origin` remote | ||
| ``` | ||
| git push --set-upstream origin <relevant-branch-name> | ||
| ``` | ||
| Note: replace `<relevent-branch-name>` with the name of the branch you created in step 3 | ||
|
|
||
| #### 9. Navigate to your forked repository on GitHub and click the "Compare & pull request" button | ||
|
|
||
| <details><summary><b>see screenshot</b></summary> | ||
|
|
||
|  | ||
|
|
||
| </details> |