From 5f52139062608c87d58d6c79e00ca33e04e8a57e Mon Sep 17 00:00:00 2001 From: Alex Verdin Date: Fri, 18 Jun 2021 19:08:00 -0700 Subject: [PATCH] Contributing.md changes (#1471) * Got Akibs Changes * Update CONTRIBUTING.md file * Accepted incoming merge conflict * Made github username wording more consistent * Added documentation for using Docker back to the file * Added git status code back to file * Changed edits to pull request * Changed wording of issue and pull request headers * Fixed broken link in edits to a pull request * Changed wording of first pull request in bottom greeting * Removed unnecessary text * Added info about VS Code and moved Changes from Upsream section * Added hfla-site slack link * Made changes suggested by alyssa * Update CONTRIBUTING.md Minor changes. Made two changes to the file. Co-authored-by: Josh Bubar <53061723+jbubar@users.noreply.github.com> Co-authored-by: Alyssa <38295612+alyssabenipayo@users.noreply.github.com> --- CONTRIBUTING.md | 574 +++++++++++++++++++++++++----------------------- 1 file changed, 302 insertions(+), 272 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 341f75e2aa..1a28ab9240 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,383 +1,417 @@ # How to Contribute -To develop the site, you'll need to first clone the repository on to your computer. For new Git users, see the [Using Git](#using-git) section below.

+👍🎉 First off, thanks for taking the time to contribute! 🎉👍 -# OVERVIEW -**Set up** -1. [Join the Repo Team](#step-1-become-a-member-of-the-repository-team) +The following is a set of guidelines for contributing to the website repository, which is hosted on GitHub. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request. -2. [Using Git](#using-git) and [Fork the Repo](#step-2-fork-the-repository) +** The guide below assumes that you have completed the onboarding process which includes joining the Hack for LA Slack, GitHub, and Google Drive. If you have not been onboarded, please refer to the [Getting Started Page](https://www.hackforla.org/getting-started). -3. [Clone to your local machine](#step-3-clone-your-online-repository-to-your-local-computer) +** If you need a text editor to work on code, [VS Code](https://code.visualstudio.com/download) is recommended by the team, but feel free to use a text editor of your choice. -4. [Set up Docker](#step-4-setting-up-docker) +** If you have any other questions about your contributing process, feel free to reach out to the team in the [#hfla-site](https://hackforla.slack.com/archives/C4UM52W93) slack channel. +

-**Before you start working on an issue** -5. [Read Hack for LA's Site Architecture to get acquainted with how the website is structured](https://github.com/hackforla/website/wiki/Hack-for-LA's-Site-Architecture) +# Table of Contents +### Setting up the development environment +1. [Join the repository team](#Join-the-repository-team) +2. [Fork the repository](#Fork-the-repository) +3. [Clone the forked repository](#Clone-the-forked-repository) +4. [Set up Docker](#Set-up-Docker-[4]) +5. [Build and serve the website locally](#Build-and-serve-the-website-locally) +### Working on an issue and making a pull request +1. [Working on an issue](#Working-on-an-issue) + - [Check current branch](#Check-current-branch) + - [Create a new branch where you will work on your issue](#Create-a-new-branch-where-you-will-work-on-your-issue) + - [Prepare your changes to push to your repository](#Prepare-your-changes-to-push-to-your-repository) + + - [Check upstream before you push](#Check-upstream-before-you-push) +2. [Making a pull request](#Making-a-pull-request) +### Resources and Documentation +1. [Hack for LA's Site Architecture](https://github.com/hackforla/website/wiki/Hack-for-LA's-Site-Architecture) +2. [GitHub Pages](https://pages.github.com/) +3. [Jekyll Docs](https://jekyllrb.com) +4. [Github Guides](https://guides.github.com/) +5. [Docker](https://docs.docker.com/get-started/) + - [Docker Compose](https://docs.docker.com/compose/gettingstarted/) + - [Docker Desktop](https://docs.docker.com/install/) -6. [Switch to new issue branch before you start making changes](#step-6-work-on-an-issue-using-git) +# Setting up the development environment +## Join the repository team -**After you've worked on your issue and before you make a pull request:** - -7. [Check upstream before you push](#step-7-check-upstream-before-you-push). - -7a. [No changes in the upstream repo](#step-7a-no-changes-in-the-upstream-repository) - -**Or** - -7b. [Conflicting changes in the upstream repo](#step-7b-conflicting-changes-in-the-upstream-repository) and how to resolve them - -**Okay. You're good to go!** - -8. [Status updates](#step-8-status-updates) - -9. [Complete the pull request](#step-9-complete-the-pull-request) - ---- - -### Forking and cloning the repository with proper security - -#### Step 1: Become a member of the repository Team - -In the `hfla-site` slack channel, send your GitHub name to the project manager (or on the slack channel thread) and we'll add you as a member to the GitHub repository Team. +In the `hfla-site` Slack channel, send an introductory message with your GitHub handle/username asking to be added to the Hack for LA website GitHub repository (this repository). Once you have accepted the GitHub invite (comes 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 +1. Make your own Hack for LA GitHub organization membership public by following this [guide](https://help.github.com/en/articles/publicizing-or-hiding-organization-membership#changing-the-visibility-of-your-organization-membership). -1. Setup two factor authentication on your account https://github.com/hackforla/governance/issues/20 +2. Set up two-factor authentication on your account by following this [guide](https://docs.github.com/en/github/authenticating-to-github/configuring-two-factor-authentication). -## Using Git +## Fork the repository -This section discusses some tips and best practices for working with Git. +You can fork the hackforla/website repository by clicking +. A fork is a copy of the repository that will be placed on your GitHub account. -### Making changes, committing and pushing +It should create a URL that looks like the following -> `https://github.com//website`. -1. Generally changes start on your local clone of your fork of this repository, in your own branch. +For example -> `https://github.com/octocat/website`. -1. Commit your changes with a comment related to the issue it addresses to your local repository. +Note that this forked copy is a remote version on GitHub. It is not yet on your local machine. -1. Push that commit(s) to your online GitHub fork. +## Clone the forked repository -1. From the `hackforla` repository, create a Pull Request which asks `hackforla` to pull changes from your fork into the main repository. +Before cloning your forked repository to your local machine, you must have Git installed. You can find instructions for installing Git for your operating system [**here**](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git). -1. After the owner of the `hackforla` repository approves and merges your Pull Request, your changes will be live on the website. +The following steps will create a local copy of the repository on your machine. -#### Step 2: Fork the repository + 1. Create a new folder on your machine that will contain `hackforla` projects. -In https://github.com/hackforla/website, look for the fork icon in the top right. Click it and create a fork of the repository. + In your command line interface (Terminal, Git Bash, Powershell), navigate into the folder(directory) you just created. + + For example: + ```bash + cd Desktop + cd hackforla + ``` + + and run the following commands: + + ```bash + git clone https://github.com//website.git + ``` + + For example: + ```bash + git clone https://github.com/octocat/website.git + ``` -For git beginners, a fork is a copy of the repository that will be placed on your GitHub account url. + You should now have a new folder in your `hackforla` folder called `website`. Verify this by changing into the new directory: + ```bash + cd website + ``` -It should create a copy here: https://github.com/your_GitHub_user_name/website, where `your_GitHub_user_name` is replaced with exactly that. + 2. Verify that your local cloned repository is pointing to the correct `origin` URL (that is, the forked repo on your own Github account): -Note that this copy is on a remote server on the GitHub website and not on your computer yet. + ```bash + git remote -v + ``` + You should see `fetch` and `push` URLs with links to your forked repository under your account (i.e. `https://github.com//website.git`). You are all set to make working changes to the website on your local machine. -If you click the icon again, it will not create a new fork but instead give you the URL associated with your fork. + However, we still need a way to keep our local repo up to date with the deployed website. To do so, you must add an upstream remote to incorporate changes made while you are working on your local repo. Run the following to add an upstream remote URL & update your local repo with recent changes to the `hackforla` version: -#### Step 3: Clone your online repository to your local computer + ```bash + git remote add upstream https://github.com/hackforla/website.git + git fetch upstream + ``` -For git beginners, this process will create a third copy of the repository on your local desktop. + After adding the upstream remote, you should now see it if you again run `git remote -v` : + ```bash + origin https://github.com//website.git (fetch) + origin https://github.com//website.git (push) + upstream https://github.com/hackforla/website.git (fetch) + upstream https://github.com/hackforla/website.git (push) + ``` +
+ If you accidentally cloned using the repository URL from the HackForLA Github (instead of the fork on your Github) + -First create a new folder on your desktop that will contain `hackforla` projects. + 1) Set your forked repo on your Github as an `origin` remote: -In your shell, navigate there then run the following commands: + ```bash + git remote set-url origin https://github.com//website.git + ``` -```bash -git clone https://github.com/your_GitHub_user_name/website.git -``` + 2) Add another remote called `upstream` that points to the `hackforla` version of the repository. This will allow you to incorporate changes later: -You should now have a new folder in your `hackforla` folder called `website`. Verify this by changing into the new directory: -```bash -cd website -``` - -Next, verify that your local cloned repository is pointing to the correct `origin` URL (that is, the forked repo on your own Github account): + ```bash + git remote add upstream https://github.com/hackforla/website.git + ``` +
+## Set up Docker -```bash -git remote -v -``` -You should see `fetch` and `push` URLs with links to your forked repository under your account (i.e. `https://github.com/YOURUSERNAME/website.git`). You are all set to make working changes to the website on your local machine. +Docker is the recommended approach to quickly getting started with local development. Docker helps create a local/offline version of the hackforla.org website on your computer so you can test out your code before submitting a pull request. -However, we still need a way to keep our local repo up to date with the deployed website. To do so, you must add an upstream remote to incorporate changes made while you are working on your local repo. Run the following to add an upstream remote URL & update your local repo with recent changes to the `hackforla` version: +The recommended installation method for your operating system can be found [here](https://docs.docker.com/install/). Feel free to reach out in the hfla slack channel if you have trouble installing docker on your system -```bash -git remote add upstream https://github.com/hackforla/website.git -git fetch upstream -``` -After adding the upstream remote, you should now see it if you again run `git remote -v` : -```bash -origin https://github.com/YOURUSERNAME/website.git (fetch) -origin https://github.com/YOURUSERNAME/website.git (push) -upstream https://github.com/hackforla/website.git (fetch) -upstream https://github.com/hackforla/website.git (push) +More on using Docker and the concepts of containerization: -``` -If you accidentally cloned using the repository URL from the HackForLA Github (instead of the fork on your Github), then you can correct that with the following two commands: +* [Get started with Docker](https://docs.docker.com/get-started/) -1) Set your forked repo on your Github as an `origin` remote: +
+Docker Installation Troubleshooting -```bash -git remote set-url origin https://github.com/your_user_name/website.git -``` +If you are on Windows and get 'You are not allowed to use Docker, you must be in the "docker-users" group' as an error message, the following wiki page is a guide for solving te issue: +- [Windows docker-users group error guide](https://github.com/hackforla/website/wiki/Adding-local-user-accounts-to-the-docker-users-group-on-Windows-10) -2) Add another remote called `upstream` that points to the `hackforla` version of the repository. This will allow you to incorporate changes later: +Installing WSL2 on windows +- https://docs.microsoft.com/en-us/windows/wsl/install-win10 +
-```bash -git remote add upstream https://github.com/hackforla/website.git -``` -#### Step 4: Setting up Docker +## Build and serve the website locally +### Build Up -Docker is the recommended approach to quickly getting started with local development. (ELI5: Docker helps create a local/offline version of the hackforla.org website on your computer so you can test out your code before submitting a pull request). +- This command starts a jekyll server locally. The server watches for changes to +the source files and rebuilds and refreshes the site automatically in your browser. -There are two pre-requisites: Docker and Docker Compose. -The recommended installation method is [Docker Desktop](https://docs.docker.com/install/) for Windows 10 64-bit, -Mac, and Linux users. + Navigate to within the `website` directory that you cloned earlier in your terminal then run the below command -More on using Docker and the concepts of containerization: + ```bash + docker-compose up + ``` -* [Get started with Docker](https://docs.docker.com/get-docker/) -* [Get started with Docker Compose](https://docs.docker.com/compose/gettingstarted/) + Running the above command will result in the following output in your terminal -*Ensure you run the `docker` commands below from a shell inside the local directory containing your clone of this repository.* +
+ Terminal Output -If you are on Windows and get 'You are not allowed to use Docker, you must be in the "docker-users" group' as an error message, the following wiki page is a guide for solving te issue: -* [Windows docker-users group error guide](https://github.com/hackforla/website/wiki/Adding-local-user-accounts-to-the-docker-users-group-on-Windows-10) + ```bash + Starting hfla_site ... done + Attaching to hfla_site + hfla_site | ruby 2.7.1p83 (2020-03-31 revision a0c7c23c9c) [x86_64-linux-musl] + hfla_site | Configuration file: _config.yml + hfla_site | Configuration file: _config.docker.yml + hfla_site | Source: . + hfla_site | Destination: /srv/jekyll/_site + hfla_site | Incremental build: enabled + hfla_site | Generating... + hfla_site | done in 33.641 seconds. + hfla_site | Auto-regeneration may not work on some Windows versions. + hfla_site | Please see: https://github.com/Microsoft/BashOnWindows/issues/216 + hfla_site | If it does not work, please upgrade Bash on Windows or run Jekyll with --no-watch. + hfla_site | Auto-regeneration: enabled for '.' + hfla_site | LiveReload address: http://0.0.0.0:35729 + hfla_site | Server address: http://0.0.0.0:4000/ + hfla_site | Server running... press ctrl-c to stop. + ``` -### Build and serve the website locally +
-This command starts a jekyll server locally. The server watches for changes to -the source files and rebuilds and refreshes the site automatically in your browser. + When you see the above output, it means the site is now running and now you can browse to http://localhost:4000 -```bash -docker-compose up -``` +### Tear Down -Now browse to http://localhost:4000 + - To stop and completely remove the jekyll server (i.e. the running Docker container): -### Tear down + *(do this anytime Docker or jekyll configuration or other repository settings change)* -To stop and completely remove the jekyll server (i.e. the running Docker container): + ```bash + docker-compose down + ``` -*(do this anytime Docker or jekyll configuration or other repository settings change)* -```bash -docker-compose down -``` + To stop the server, but not destroy it (often sufficient for day-to-day work): -To stop the server, but not destroy it (often sufficient for day-to-day work): + ```bash + docker-compose stop + ``` -```bash -docker-compose stop -``` + Bring the same server back up later with: -Bring the same server back up later with: + ```bash + docker-compose up + ``` -```bash -docker-compose up -``` -
+# Working on an issue and making a pull request -#### Step 5: Read [Hack for LA's Site Architecture](https://github.com/hackforla/website/wiki/Hack-for-LA's-Site-Architecture) to get acquainted with how the website is structured +## Working on an issue -#### Step 6: Work on an issue using git + > - If you are using Visual studios code you can use the Git graphical user interface to stage your changes. For instructions check out the [Git gui wiki] (https://github.com/hackforla/website/wiki/Using-Git-GUI-(Graphical-user-Interface)-in-Visual-Studios-Code) + > Alternatively you can follow the instructions below to stage changes through the terminal. Create a new branch for each issue you work on. Doing all your work on topic branches leaves your repository's main branch (named `gh-pages`) unmodified and greatly simplifies keeping your fork in sync with the main project. -a) Check current branch - -The `git branch` command will let you know what branch you are in, and what branch names are already in use. - -```bash -git branch -``` - -You will see a list of all of your branches. There will be a star (`*`) next to the branch that you are currently in. By default you should start on the `gh-pages` branch. +1. ### Check current branch -Note: when you work on future issues, you must always be in the `gh-pages` branch when creating a new branch. + The `git branch` command will let you know what branch you are in, and what branch names are already in use. -If you are not currently in the `gh-pages` branch, run the following command to return to it: + ```bash + git branch + ``` -```bash -git checkout gh-pages -``` + You will see a list of all of your branches. There will be a star (`*`) next to the branch that you are currently in. By default you should start on the `gh-pages` branch. -b) Create a new branch where you will work on your issue + ** *when you work on future issues, you must always be in the `gh-pages` branch when creating a new branch.* -The `git checkout` command will create and change to a new branch where you will do the work on your issue. In git, the checkout command lets you navigate between different branches. Using the `-b` flag you can create a new branch and immediately switch into it. + If you are not currently in the `gh-pages` branch, run the following command to return to it: -To create a new issue branch, and switch into it: + ```bash + git checkout gh-pages + ``` -```bash -git checkout -b fix-logo-width-311 -``` +2. ### Create a new branch where you will work on your issue -The text after the `-b`, in the example `fix-logo-width-311`, will be the name of your new branch. Choose a branch name that relates to the issue you're working on. (No spaces!) + The `git checkout` command will create and change to a new branch where you will do the work on your issue. In git, the checkout command lets you navigate between different branches. Using the `-b` flag you can create a new branch and immediately switch into it. -The format should look like the scheme above where the words are a brief description of the issue that will make sense at a glance to someone unfamiliar with the issue. + To create a new issue branch, and switch into it: -No law of physics will break if you don't adhere to this scheme, but laws of git will break if you add spaces. + ```bash + git checkout -b fix-logo-width-311 + ``` -When you've finished working on your issue, follow the steps below to prepare your changes to push to your repository. + The text after the `-b`, in the example `fix-logo-width-311`, will be the name of your new branch. Choose a branch name that relates to the issue you're working on. (No spaces!) -c) Prepare your changes to push to your repository -Once you are done with the work on your issue you will push it to your repository. Before you can push your work to your repository, you will stage and commit your changes. These two commands are similar to the save command that you have used to in other programs. + The format should look like the scheme above where the words are a brief description of the issue that will make sense at a glance to someone unfamiliar with the issue. -> - If you are using Visual studios code you can use the Git graphical user interface to stage your changes. For instructions check out the [Git gui wiki] (https://github.com/hackforla/website/wiki/Using-Git-GUI-(Graphical-user-Interface)-in-Visual-Studios-Code) -> Alternatively you can follow the instructions below to stage changes through the terminal. + *No law of physics will break if you don't adhere to this scheme, but laws of git will break if you add spaces.* + When you've finished working on your issue, follow the steps below to prepare your changes to push to your repository. --Use the `git add` command to stage your changes. -This command prepares your changes before you commit them. You can stage files one at a time using the filename. +3. ### Prepare your changes to push to your repository -Run the command: -```bash -git add “filename.ext” -``` + Once you are done with the work on your issue you will push it to your repository. Before you can push your work to your repository, you will stage and commit your changes. These two commands are similar to the save command that you have used to in other programs. --Use the `git status` command to see what files are staged. + ** *If you are using Visual studios code you can use the Git graphical user interface to stage your changes. For instructions check out the [Git Gui Wiki](https://github.com/hackforla/website/wiki/Using-Git-GUI-(Graphical-user-Interface)-in-Visual-Studios-Code)* + -This command will list the files that have been staged. These are the files that will be committed (saved) when you run the next command, `git commit`. Please be sure all your staged changes are relevant to the issue you are working on. If you find you have included unrelated changes, please unstage them before making this commit - and then make a new commit for the unrelated changes. (The commands for unstaging commits are provided in the output of your `git status` command.) + - Use the `git add` command to stage your changes. + This command prepares your changes before you commit them. You can stage files one at a time using the filename. -```bash -git status -``` --Use the `git reset HEAD` command to remove a staged file. + Run the command: + ```bash + git add “filename.ext” + ``` -This command will remove a file that has been staged. This file will not be committed (saved) when you run the next command, `git commit`. This only works if the wrong files were added, but they were not yet committed. The file will be removed from the staging area, but not actually deleted: -```bash -git reset HEAD “filename.ext” -``` + - Use the `git status` command to see what files are staged. --Use the `git commit` command + This command will list the files that have been staged. These are the files that will be committed (saved) when you run the next command, `git commit`. Please be sure all your staged changes are relevant to the issue you are working on. If you accidentally included unrelated changes, please unstage them before making this commit, and then make a new commit for the unrelated changes. (The commands for unstaging commits are provided in the output of your `git status` command.) + + ```bash + git status + ``` -This command saves your work, and prepares it to push to your repository. Use the `-m` flag to quickly add a message to your commit. Your message should be a short description of the issue you are working. It will be extremely helpful if other people can understand your message, so try to resist the temptation to be overly cryptic. -To commit your changes with a message, run: -```bash -git commit -m “insert message here” -``` + - Use the `git reset HEAD` command to remove a staged file. -Congratulations! You are now ready to push your work to your repository. + This command will remove a file that has been staged. This file will not be committed (saved) when you run the next command, `git commit`. This only works if the wrong files were added, but they were not yet committed. The file will be removed from the staging area, but not actually deleted: + ```bash + git reset HEAD “filename.ext” + ``` -#### Step 7: Check upstream before you push + - Use the `git commit` command -Before you push your local commits to your repository, check to see if there have been updates made in the main Hack For LA website repository. `git fetch` will check remote repositories for changes without altering your local repository. + This command saves your work, and prepares it to push to your repository. Use the `-m` flag to quickly add a message to your commit. Your message should be a short description of the issue you are working. It will be extremely helpful if other people can understand your message, so try to resist the temptation to be overly cryptic. -```bash -git fetch upstream -``` + To commit your changes with a message, run: + ```bash + git commit -m “insert message here” + ``` +** If you do not see the changes you applied when you run `docker-compose up`, delete `_site` directory and `.jekyll-metadata` file and restart docker. This will force docker to rebuild the whole site. + +4. ### Check upstream before you push -##### Step 7a: No changes in the upstream repository + Before you push your local commits to your repository, check to see if there have been updates made in the main Hack For LA website repository. `git fetch` will check remote repositories for changes without altering your local repository. -If you do not see any output, there have not been any changes in the -main Hack for LA website repository since the last time you -checked. So it is safe to push your local commits to your fork. + ```bash + git fetch upstream + ``` -If you just type `git push` you will be prompted to create a new branch in your GitHub repository. The more complete command below will create a new branch on your copy of the website repository, and then push your local branch there. The name at the end of this command should be the same as the name of the local branch that you created back in step 6, as in the example below: + -
+ No changes in the upstream repository -```bash -git push --set-upstream origin fix-logo-width-311 -``` + If you do not see any output, there have not been any changes in the + main Hack for LA website repository since the last time you + checked. So it is safe to push your local commits to your fork. -##### Step 7b: conflicting changes in the upstream repository + If you just type `git push` you will be prompted to create a new branch in your GitHub repository. The more complete command below will create a new branch on your copy of the website repository, and then push your local branch there. The name at the end of this command should be the same as the name of the local branch that you created back in step 3, as in the example below: -When you check the upstream repository, you may see output like this: + ```bash + git push --set-upstream origin fix-logo-width-311 + ``` +
+ -
+ Conflicting changes in the upstream repository -```bash -Fetching upstream -remote: Enumerating objects: 11, done. -remote: Counting objects: 100% (11/11), done. -remote: Compressing objects: 100% (7/7), done. -remote: Total 11 (delta 5), reused 7 (delta 4), pack-reused 0 -Unpacking objects: 100% (11/11), 8.25 KiB | 402.00 KiB/s, done. -From https://github.com/hackforla/website - + 770d667...14f9f46 Bonnie -> hackforla/Bonnie (forced update) - * [new branch] bonnie -> hackforla/bonnie - 5773ebe..0c86ecd gh-pages -> hackforla/gh-pages -``` - -You can safely ignore changes in other issue branches, such as -`bonnie` above. But if you see changes in gh-pages, as in -`5773ebe..0c86ecd gh-pages -> hackforla/gh-pages`, you should -incorporate those changes into your repository before merging or -rebasing your issue branch. Use the [instructions below](#incorporating-changes-from-upstream) -to bring your fork up to date with the main repository. + When you check the upstream repository, you may see output like this: + ```bash + Fetching upstream + remote: Enumerating objects: 11, done. + remote: Counting objects: 100% (11/11), done. + remote: Compressing objects: 100% (7/7), done. + remote: Total 11 (delta 5), reused 7 (delta 4), pack-reused 0 + Unpacking objects: 100% (11/11), 8.25 KiB | 402.00 KiB/s, done. + From https://github.com/hackforla/website + + 770d667...14f9f46 Bonnie -> hackforla/Bonnie (forced update) + * [new branch] bonnie -> hackforla/bonnie + 5773ebe..0c86ecd gh-pages -> hackforla/gh-pages + ``` -### Incorporating changes from upstream + You can safely ignore changes in other issue branches, such as + `bonnie` above. But if you see changes in gh-pages, as in + `5773ebe..0c86ecd gh-pages -> hackforla/gh-pages`, you should + incorporate those changes into your repository before merging or + rebasing your issue branch. Use the [instructions below](#incorporating-changes-from-upstream) + to bring your fork up to date with the main repository. +
+ Your fork of this repository on GitHub, and your local clone of that fork, will get out of sync with this (upstream) repository from time to time. (That's what has happened when you see something like "This branch is 1 commit behind hackforla:gh-pages" on the github website version of your hackforla repository.) -One way to keep your fork up to date with this repository is to follow -these instruction: [Syncing your fork to the original repository via the browser](https://github.com/KirstieJane/STEMMRoleModels/wiki/Syncing-your-fork-to-the-original-repository-via-the-browser) +5. ### Incorporating changes from upstream -You can also update your fork via the local clone of your fork, using -these instructions. Assuming you have a local clone with remotes -`upstream` (this repo) and `origin` (your GitHub fork of this repo): + Your fork of this repository on GitHub, and your local clone of that fork, will + get out of sync with this (upstream) repository from time to time. (That's what has happened when you see something like "This branch is 1 commit behind hackforla:gh-pages" on the github website version of your hackforla repository.) -First, you will need to create a local branch which tracks upstream/gh-pages. You will only need to do this once; you do not need to do this every time you want to incorporate upstream changes. + One way to keep your fork up to date with this repository is to follow + these instruction: [Syncing your fork to the original repository via the browser](https://github.com/KirstieJane/STEMMRoleModels/wiki/Syncing-your-fork-to-the-original-repository-via-the-browser) -Run the following two commands: + You can also update your fork via the local clone of your fork, using + these instructions. Assuming you have a local clone with remotes + `upstream` (this repo) and `origin` (your GitHub fork of this repo): -```bash -git fetch upstream -git checkout -b upstream-gh-pages --track upstream/gh-pages -``` + First, you will need to create a local branch which tracks upstream/gh-pages. You will only need to do this once; you do not need to do this every time you want to incorporate upstream changes. -If you have already created the branch upstream-gh-pages, the following commands will incorporate upstream changes: + Run the following two commands: -```bash -git checkout upstream-gh-pages # Move to the branch you want to merge with. -git pull # This updates your tracking branch to match the gh-pages branch in this repository -git checkout gh-pages # Move back to your gh-pages branch -git merge upstream-gh-pages # Merge to bring your gh-pages current. -``` -If you do all your work on topic branches (as suggested above) and keep gh-pages free of local modifications, this merge should apply cleanly. + ```bash + git fetch upstream + git checkout -b upstream-gh-pages --track upstream/gh-pages + ``` -Then push the merge changes to your GitHub fork: + If you have already created the branch upstream-gh-pages, the following commands will incorporate upstream changes: -```bash -git push -``` -If you go to your online github repository this should remove the message "This branch is x commit behind hackforla:gh-pages". + ```bash + git checkout upstream-gh-pages # Move to the branch you want to merge with. + git pull # This updates your tracking branch to match the gh-pages branch in this repository + git checkout gh-pages # Move back to your gh-pages branch + git merge upstream-gh-pages # Merge to bring your gh-pages current. + ``` + If you do all your work on topic branches (as suggested above) and keep gh-pages free of local modifications, this merge should apply cleanly. -#### Incorporating changes into your topic branch + Then push the merge changes to your GitHub fork: -To incorporate these updates from the main GitHub repository into your -topic branch, you can 'rebase' your branch onto your updated gh-pages -branch. NOTE you should only rebase if you have never pushed your -topic branch to GitHub (or shared it with another collaborator). + ```bash + git push + ``` + If you go to your online github repository this should remove the message "This branch is x commit behind hackforla:gh-pages". -```bash -git checkout fix-logo-width-311 -git rebase gh-pages -``` + #### Incorporating changes into your topic branch -If you receive warnings about conflicts, abort the rebase with `git -rebase --abort` and instead merge gh-pages into your branch. + To incorporate these updates from the main GitHub repository into your + topic branch, you can 'rebase' your branch onto your updated gh-pages + branch. NOTE you should only rebase if you have never pushed your + topic branch to GitHub (or shared it with another collaborator). -```bash -git checkout fix-logo-width-311 -git merge gh-pages -``` + ```bash + git checkout fix-logo-width-311 + git rebase gh-pages + ``` -#### Step 8: Status Updates + If you receive warnings about conflicts, abort the rebase with `git + rebase --abort` and instead merge gh-pages into your branch. -If you have not submitted a pull request make sure to write a weekly status update on your issue before the Sunday meeting. Follow the format below and add pictures of any visual changes made to the site. + ```bash + git checkout fix-logo-width-311 + git merge gh-pages + ``` -1. Progress: "What is the current status of your project? What have you completed and what is left to do?" -2. Blockers: "Difficulties or errors encountered." -3. Availability: "How much time will you have this week to work on this issue?" -4. ETA: "When do you expect this issue to be completed?" -5. Pictures: "Add any pictures of the visual changes made to the site so far." - -#### Step 9: Complete the pull request +## Making a pull request + +Start with pushing your changes to your remote repository ```bash git push --set-upstream origin fix-logo-width-311 @@ -398,13 +432,19 @@ your pull request is accepted and merged. Once you have finished working on the issue you have chosen, commit the changes to your local branch (e.g. `fix-logo-width-311`). -Important: After you completed your assignment and committed all of the changes, before moving onto your next issue and creating a new branch, you must leave your current branch and return to the `gh-pages` branch. From there you can checkout into a new branch. (This ensures you don’t accidentally include the changes from your previous branch in your new branch). +

NOTE: After completing your assignment and committing all of the changes, you must leave your current branch and return to the `gh-pages` branch. Run the following command to return to the `gh-pages` branch: ```bash -git checkout gh-pages +git checkout `gh-pages` +``` +Once your pull request is merged you can delete your branch with the following command: + +```bash +git branch -d fix-logo-width-311 ``` +Now you can move on to your next issue and create a new branch. (This ensures you don’t accidentally include the changes from your previous branch in your new branch)

From here, once your pull request is approved and merged you can pull the recent merge from the Hack For LA repository and delete your local branch: ```bash @@ -413,27 +453,17 @@ git branch -d ``` Managing branches this way will keep the commit logs cleaner on the Hack For LA repository, versus merging your completed feature branches into your local repo. -Now you are all set to work on a new PR. Start over on Step 6. - -#### Edits to pull request -If you find an error in your code or your reviewer asks you to make a change, please avoid editing your code directly from the pull request. Instead update it in your local branch first and then push it to your origin remote. This will update the original pull request. +Now you are all set to work on a new PR. Start over [here](#Working-on-an-issue). -## Useful Links +#### Edits to a pull request +If you find an error in your code or your reviewer asks you to make a change, please avoid editing your code directly from the pull request. Instead update it in your local branch first and then push it to your origin remote. This will update the original pull request. -### Supported Platforms - [ghpages](https://pages.github.com/) - [jekyll](https://jekyllrb.com) - [jekyllcli](https://jekyllrb.com/docs/usage/) -### Tutorials - -- [Github Guides](https://guides.github.com/) -- [docker](https://docs.docker.com/get-started/) -- [dockercompose](https://docs.docker.com/compose/gettingstarted/) -- [dockerdesktop](https://docs.docker.com/install/) - -### Other Documentation + For new volunteers, check this [Wiki](https://github.com/hackforla/website/wiki/How-to-Review-Pull-Requests) for more ways to contribute to the project.