website ER: Section 2.7e of CONTRIBUTING.md has code that will not work in terminal

trafficstars

Emergent Requirement - Problem

Section 2.7e of CONTRIBUTING.md has code that will not work in terminal

L705-710 of the CONTRIBUTING.md include bash code that is not executable in a terminal. This forces new members to type the code out by hand rather than copy-and-pasting, which is not in line with the documentation standard of the rest of the document.
Copy and pasting the code into the terminal will result in errors due to the comments below

Current screenshot below:

Issue you discovered this emergent requirement in

#6047

Date discovered

Feb 1, 2024

Did you have to do something temporarily

[X] YES
[ ] NO

Who was involved

@danvgar

What happens if this is not addressed

New members will be delayed in onboarding due to unnecessary confusion or requesting help in slack.

Resources

Section 2.7e of CONTRIBUTING.md

Recommended Action Items

[ ] Make a new issue
[ ] Discuss with team
[ ] Let a Team Lead know

Potential solutions [draft]

Overview

The code block for incorporating upstream changes at 2.7.e Working on an issue (5): Incorporating changes from upstream of website/CONTRIBUTING.md utilizes bash comments that may not run successfully on some operating systems or machines when copy-and-pasted. The comments need to be removed from this code block, and rewritten after the code-block for explanation purposes. .

Action Items

[ ] Open website/CONTRIBUTING.md in your IDE
[ ] Go to section "2.7.e Working on an issue (5): Incorporating changes from upstream"
[ ] At each line of code, remove all text after and inclusive of the # symbols. These are comments that prevent the code from executing properly.

```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.```

[ ] Replace the code block and subsequent text with the below

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

 
These commands do the following, respectively:
1. Moves to the branch you want to merge with.
2. Updates your tracking branch to match the gh-pages branch in this repository
3. Moves back to your gh-pages branch
4. Merges to bring your gh-pages to current.

[ ] 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

Feb 02 '24 02:02 danvgar

Don't each of these commands have to be run, and then wait for the response before you run the next? If so, each line of code must have its own copy block.

Feb 16 '24 19:02 ExperimentsInHonesty

Don't each of these commands have to be run, and then wait for the response before you run the next? If so, each line of code must have its own copy block.

That's a good question, I feel like I have run multi-line commands before but it would be good to test and verify. I see no reason they couldn't be separate code blocks as well just for reliability

Feb 16 '24 21:02 danvgar

Don't each of these commands have to be run, and then wait for the response before you run the next? If so, each line of code must have its own copy block.

That's a good question, I feel like I have run multi-line commands before but it would be good to test and verify. I see no reason they couldn't be separate code blocks as well just for reliability

Update, just confirmed you can run blocking multi-line commands on the terminal, ending each line with && \ to signal to the terminal to execute the command and wait for completion prior to trying the next command

Example:

git status && \
git add . && \
git commit && \ 
git push

Feb 16 '24 21:02 danvgar

@danvgar Please rewrite this so that each line is on its own copy block.

Feb 20 '24 01:02 ExperimentsInHonesty

Hi @danvgar, thank you for taking up this issue! Hfla appreciates you :)

Do let fellow developers know about your:- i. Availability: (When are you available to work on the issue/answer questions other programmers might have about your issue?) ii. ETA: (When do you expect this issue to be completed?)

You're awesome!

P.S. - You may not take up another issue until this issue gets merged (or closed). Thanks again :)

Feb 20 '24 01:02 github-actions[bot]

@danvgar Please rewrite this so that each line is on its own copy block.

Happy to, @ExperimentsInHonesty ! Just to clarify, which of the below two things are you asking me to do?

Rewrite this ER with more clear instructions so that it can be turned into an Issue for someone else to pick-up
Treat this ER as an Issue already and go update the CONTRIBUTING.md

Feb 20 '24 01:02 danvgar

@danvgar please update the ER with more clear instructions, then apply the "ready for dev lead" label. Thanks!

Feb 22 '24 23:02 roslynwythe

I'm back from my PTO and will jump on turning this ER into an issue by EOW Sun Mar 3. Thank you @roslynwythe !

Feb 28 '24 03:02 danvgar

@danvgar please update the ER with more clear instructions, then apply the "ready for dev lead" label. Thanks!

@roslynwythe ER has been updated with a draft issue and is ready for review. ready for dev lead label has been added.

Feb 29 '24 01:02 danvgar

Don't each of these commands have to be run, and then wait for the response before you run the next? If so, each line of code must have its own copy block.

That's a good question, I feel like I have run multi-line commands before but it would be good to test and verify. I see no reason they couldn't be separate code blocks as well just for reliability

Update, just confirmed you can run blocking multi-line commands on the terminal, ending each line with && \ to signal to the terminal to execute the command and wait for completion prior to trying the next command

Example:
git status && \
git add . && \
git commit && \ 
git push

@ExperimentsInHonesty I've tested the code block made in the ER's proposed solution's section and can confirm it runs each line successively without the need for && \ or separate code blocking.

Feb 29 '24 02:02 danvgar

Hi @danvgar In this https://github.com/hackforla/website/issues/6209#issuecomment-1953353185 Bonnie had asked for each command to be in its own copy block. I don't see those changes in the "Potential Solutions [draft]" section of this issue, but perhaps you made those changes in a new issue. If so, please provide a link to that issue. Thanks!

Apr 17 '24 07:04 roslynwythe

@danvgar