ER: Section 2.7d of CONTRIBUTING.md needs new image and upstream branch specified.

[danvgar]

Emergent Requirement - Problem

Section 2.7d of CONTRIBUTING.md needs new image and upstream branch specified.

• Image at 2.7d of CONTRIBUTING.md is broken and no longer works.
• Using the provided code for the first time provides the below error, which either (1) should be addressed in CONTRIBUTING.md as a potential scenario, or (2) the guide should be updated to specify the upstream branch in the code and avoid the error all together.

Below is the error received if just using git pull upstream without specifying an upstream branch.

$ git pull upstream

> You asked to pull from the remote 'upstream', but did not specify a branch. Because this is not the default configured remote for your current branch, you must specify a branch on the command line.

Issue you discovered this emergent requirement in

• Resolve CodeQL alert 13 "Potentially unsafe external link" #6047

Date discovered

• Feb 1, 2024

Did you have to do something temporarily

• YES - resolve error separately by specifying upstream branch
• NO

Who was involved

@danvgar

What happens if this is not addressed

• New members will experience similar confusion and delays in getting started

Resources

• website/CONTRIBUTING.md

Recommended Action Items

• Make a new issue
• Discuss with team
• Let a Team Lead know

Potential Solutions [Draft] – Update CONTRIBUTING.md Section 2.7.d with correct upstream branch

Prerequisite

1. Be a member of Hack for LA. (There are no fees to join.) If you have not joined yet, please follow the steps on our Getting Started page and attend an onboarding session.
2. Before you claim or start working on an issue, please make sure you have read our How to Contribute to Hack for LA Guide.

Overview

The readability and accuracy of our CONTRIBUTING.md documentation is crucial for ensuring a smooth onboarding process for new members. The current documentation in Section 2.7d does not provide an upstream branch for the user to pull from prior to pushing their code, and results in an error because a branch was not specified. We need to update this code to include the correct upstream branch.

Action Items

• In your local IDE, navigate to CONTRIBUTING.md
• Replace

**IMPORTANT:** Before you push your local commits to your repository, sync your fork to the main Hack For LA website repository. `git pull upstream` will ensure that your local repository is up-to-date with the main site:

```bash
git pull upstream
```

with

**IMPORTANT:** Before you push your local commits to your repository, sync your fork to the main Hack For LA website repository. `git pull upstream gh-pages` will ensure that your local repository is up-to-date with the main site:

```bash
git pull upstream gh-pages
```

• With CONTRIBUTING.md still open, make a note of the section in which the replaced content appears, so that you will know where to look in the document to preview the change.
• Changes to CONTRIBUTING.md cannot be tested locally, rather they must be tested after pushing the issue branch to your fork of the repository. Push your issue branch in the usual manner, but before creating the Pull Request, check your updates using this test URL. Also store the test URL for use in a later step:

https://github.com/[REPLACE WITH GITHUB HANDLE]/website/blob/[REPLACE WITH NAME OF ISSUE BRANCH]/CONTRIBUTING.md

(for example: https://github.com/bonniewolfe/website/blob/issue-branch-1234/CONTRIBUTING.md)

• Create a pull request with your changes. In the Pull Request, after the "Why did you make the changes" section, add this line to help reviewers, replacing the text in brackets (and the brackets) with the test URL from the previous Action Item.

For Reviewers: Do not review changes locally, rather, review changes at [REPLACE WITH TEST URL]

Resources/Instructions

• CONTRIBUTING.md
• Getting started with writing and formatting on GitHub
• This issue is part of ER: Section 2.7d of CONTRIBUTING.md needs new image and upstream branch specified. #6208

Potential Solutions [Draft] – Fix broken image in CONTRIBUTING.md Section 2.7.d

Prerequisite

1. Be a member of Hack for LA. (There are no fees to join.) If you have not joined yet, please follow the steps on our Getting Started page and attend an onboarding session.
2. Before you claim or start working on an issue, please make sure you have read our How to Contribute to Hack for LA Guide.

Overview

The readability and accuracy of our CONTRIBUTING.md documentation is crucial for ensuring a smooth onboarding process for new members. The current documentation in Section 2.7d contains a broken image that needs to be fixed.

Action Items

• In your local IDE, navigate to CONTRIBUTING.md
• Replace

You can also sync your fork directly on GitHub by clicking "Sync Fork" at the right of the screen and then clicking "Update Branch"

<details>
  <summary><strong>Click here</strong> to see how to sync the fork on GitHub</summary>
  <img src="https://github-production-user-asset-6210df.s3.amazonaws.com/5314153/307199130-f50cd9c2-a37c-432f-9745-df8325fd581a.png" />
</details>

with

You can also sync your fork directly on GitHub by clicking "Sync Fork" at the right of the screen and then clicking "Update Branch"

<details>
  <summary><strong>Click here</strong> to see how to sync the fork on GitHub</summary>
  <img src="https://raw.githubusercontent.com/wiki/hackforla/website/images/how-to-review-pull-requests/step3-sync-demo.gif" />
</details>

• With CONTRIBUTING.md still open, make a note of the section in which the replaced content appears, so that you will know where to look in the document to preview the change.
• Changes to CONTRIBUTING.md cannot be tested locally, rather they must be tested after pushing the issue branch to your fork of the repository. Push your issue branch in the usual manner, but before creating the Pull Request, check your updates using this test URL. Also store the test URL for use in a later step:

https://github.com/[REPLACE WITH GITHUB HANDLE]/website/blob/[REPLACE WITH NAME OF ISSUE BRANCH]/CONTRIBUTING.md

(for example: https://github.com/bonniewolfe/website/blob/issue-branch-1234/CONTRIBUTING.md)

• Create a pull request with your changes. In the Pull Request, after the "Why did you make the changes" section, add this line to help reviewers, replacing the text in brackets (and the brackets) with the test URL from the previous Action Item.

For Reviewers: Do not review changes locally, rather, review changes at [REPLACE WITH TEST URL]

Resources/Instructions

• CONTRIBUTING.md
• Getting started with writing and formatting on GitHub
• This issue is part of ER: Section 2.7d of CONTRIBUTING.md needs new image and upstream branch specified. #6208

[ExperimentsInHonesty]

@danvgar So what are you suggesting for the changes? Also, choose the checkbox for the Recommended Action Items

[danvgar]

@danvgar So what are you suggesting for the changes? Also, choose the checkbox for the Recommended Action Items

I am not entirely sure what the solution should be, but I believe if the code is modified to include the upstream branch, it should work. I can dig a bit deeper and provide a step-by-step proposal if that's what you'd like, just let me know.

I talked with @roslynwythe and it sounds like this should have been two Emergent Requests / Issues, since the broken image link is a separate task.

[roslynwythe]

Hi @danvgar

• I realized that Section 2.7d has recently been updated to include the full instruction for pulling the upstream gh-pages, so you can remove that from the ER
• I found an animated gif we can use to replace the broken image, so please update the "Potential Solutions" section

how to sync your forked repo to the main repo

- [ ] Please note, that when you write an issue from ER, you should include a link back to the ER, in the Resources section. Something like "This issue was created from #6208". If you place a hyphen in front of that statement, GitHub will expand the issue number into a link. You should also create a comment in the ER with a link to the new issue.

Thank you for writing this ER. When you have made the updates, please apply the "ready for dev lead" label and ping me via Slack. If you wish to write the issue for fixing the broken images, go ahead and self-assign this ER.

[danvgar]

@roslynwythe ER description has been updated with draft solution instructions. I'm not sure what you meant about CONTRIBUTING.md showing the correct upstream branch code because it is still showing incomplete code to me. After some research and testing I can confirm it should be git pull upstream gh-pages.

I've created two new issues for approval below.

• Update CONTRIBUTING.md Section 2.7.d with correct upstream branch #6581
• Fix broken image in CONTRIBUTING.md Section 2.7.d #6582

[roslynwythe]

Thank you @danvgar for writing these issues. This ER will be closed "as completed".