Update pr instructions GHA with URL for reviewing changes to CONTRIBUTING.md

[roslynwythe]

Overview

When a Pull Request includes changes to CONTRIBUTING.md, the current PR instructions are not accurate, because CONTRIBUTING.md cannot be previewed locally, rather it must be previewed on a GitHub repository. We need to instruct the PR author and reviewers to preview changes using the URL of CONTRIBUTING.md on the issue branch in the contributor's fork of the website repository.

Details

Here is the new instruction which should be appended to the existing instruction:

Note that CONTRIBUTING.md cannot previewed locally; rather it should be previewed at this URL:

https://github.com/[REPLACE WITH nameOfCollaborator]/website/blob/[NAME OF FROM BRANCH]/CONTRIBUTING.md

where nameOfCollaborator and nameOfFromBranch refer to the variables with the same names in create-instruction.js¹.
The text above should be stored in a new template github-actions/pr-instructions/pr-contrib-instructions-template.md and the variable replacement should be done in create-instruction.js² as detailed below.

The suggested strategy is to reformat the JS by moving the formatComment function into create-instruction.js so that regardless of how many instructions we provide in the PR (each with its own template), only a single composite instruction will be stored in the artifact, and in create-instruction.js, we have access to the PR context so that in the future, we could include or exclude instructions based on the files that were changed.

Action Items

• Become familiar with the resources describing the HfLA GHA archtecture² and testing procedures³ as well as the resource describing the PR Instructions GHA⁴ and understand the scripts create-instruction.js¹ and post-comment.js⁵
• The recommended approach is to update create-instruction.js¹ so that it contains a larger instruction composed of two parts:
  • part 1 is the current pr instruction, but now it will be created in create-instruction.js¹ by merging the existing instruction string into the existing pr-instructions-template.md⁶. Previously this step was performed in formatComment() so that function will have to be moved from post-comment.js⁵ into create-instruction.js⁷
  • part 2 is the new portion described in the Details section above. It will be created by merging a new string previewContributingURL into the new template.
• To propose an alternative approach, discuss with merge team/ dev lead

Resources/Instructions

Footnotes

1. https://github.com/hackforla/website/blob/gh-pages/github-actions/pr-instructions/create-instruction.js ↩ ↩² ↩³ ↩⁴

2. Hack for LA's GitHub Actions ↩ ↩²

3. HfLA GitHub Actions ↩

4. GHA: pr instructions ↩

5. https://github.com/hackforla/website/blob/gh-pages/github-actions/pr-instructions/post-comment.js ↩ ↩²

6. pr-instructions-template.md ↩

7. PR Instructions Template ↩

[roslynwythe]

I suggest adding time-sensitive to this issue, because we have quite a few changes to CONTRIBUTING.md coming up, and it would be nice to have these enhanced instructions for devs to test those changes.

I self-assigned it and went ahead with the changes. It can be previewed at roslynwythe#40

[github-actions]

Hi @roslynwythe, 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 :)

[roslynwythe]

The problem is that the pr instruction contains backticks and those cause a problem in github artifacts

[ExperimentsInHonesty]

@roslynwythe If you are working on this issue, go ahead and remove the ready for dev lead label and put it in the In progress column.