ER: update the pull request contributing guidelines

[ino-iosdev]

Emergent Requirement - Problem

This problem was brought up during the weekly Sunday meeting on 06/09/24.

We want the title of the PR to clearly summarize how the dev resolved the issue. When devs unnecessarily include the issue number in the title, the issue number collides with the PR number making it unclear which is which, and is a detriment to clear communication. Here is an example:

Issue you discovered this emergent requirement in

• #6982
• #6984

Date discovered

• 06/09/24

Did you have to do something temporarily

• [x] YES
• [ ] NO

Who was involved

@ino-iosdev @t-will-gillis

What happens if this is not addressed

• Repetitive change request in PR review
• Reduce PR review efficiency

Resources

CONTRIBUTING.md#part-3-pull-requests

Recommended Action Items

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

Potential solutions [draft]

In CONTRIBUTING.md, Section 3.1.b.i. Replace:

* When the pull request is opened, the title input box will be the where the cursor defaults to.
* The default title will be your last commit message from your branch.
  * Please change it to provide a summary of what you did.
  * For our example (PR [Update Care Link in Credits Page - #2131](https://github.com/hackforla/website/pull/2131)), [@adrian-zaragoza](https://github.com/adrian-zaragoza) provided the following title:

  ````
  Update Care Link in Credits Page
  ````

**Advice:** Provide a 4-12 word summary of your resolution to the issue you are handling.

with:

* When the pull request is opened, the cursor will be located in the title input box, and the default title will be your last commit message from your branch.
* Change the title to a short summary of what you did on the issue: 
  * **Advice:** Provide a 4-12 word description of your resolution to the issue
  * For our example, [@adrian-zaragoza](https://github.com/adrian-zaragoza) provided the following title:

      `Update Care Link in Credits Page`

  * **Note:** Upon creation, the pull request number will be appended to the title automatically. To avoid confusion, please **do not include** the issue number in the title. 
  * The final title from our example is:  
      [Update Care Link in Credits Page #2131](https://github.com/hackforla/website/pull/2131) 

[github-actions[bot]]

Hi @ino-iosdev.

Please don't forget to add the proper labels to this issue. Currently, the labels for the following are missing:

• Complexity, Role, Feature

NOTE: Please ignore this comment if you do not have 'write' access to this directory.

To add a label, take a look at Github's documentation here.

Also, don't forget to remove the "missing labels" afterwards. To remove a label, the process is similar to adding a label, but you select a currently added label to remove it.

After the proper labels are added, the merge team will review the issue and add a "Ready for Prioritization" label once it is ready for prioritization.

Additional Resources:

• Wiki: How to create issues
• Wiki: How to read and interpret labels

[t-will-gillis]

Hey @ino-iosdev good start on this! Here are some suggestions:

• If this were my ER, I would approach this more from the standpoint of “We want the title of the PR to clearly summarize how the dev resolved the issue. When devs unnecessarily include the issue number in the title, the issue number collides with the PR number making it unclear which is which, and is a detriment to clear communication.” Or something to that effect.
• It may be helpful to crop down the first screenshot to emphasize the circled area.
• I think that it would help to remove the second screenshot. I understand what you are saying, but I think the first screenshot illustrates the point and the second only distracts from your argument. Also, although it might not be strictly the case in this exact instance, when we link them, the issue and PR number usually appears at the end.
• For the “Potential solutions [draft]”, you will want to reference a specific area of code where the solution would be applied- think of it as you are writing an issue and need to tell a dev exactly what needs to be changed. For example, since you are recommending a change to the way devs title their PRs, the applicable code is CONTRIBUTING.md, Section 3.1.b.i. around or after line 889 (your 2nd screenshot). Where our docs say - Please change it to provide a summary of what you did. you could recommend adding another bullet - Note: Please do not include the issue number in the PR title; a PR number will be added automatically. or some such.

For the labels: role: back end/devOps, complexity: depending on the change this might be a good first issue, and feature: this would be p-feature: onboarding/contributing.md

One final thing, if this is approved, you should volunteer to write the issue for it.

[HackforLABot]

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

[DrAcula27]

Availability: weekdays after 3pm Pacific ETA: 27 October 2024

[DrAcula27]

@t-will-gillis The issue for this ER has been made.

• #7641

Let me know if there are any questions/concerns!

[t-will-gillis]

Closing this ER, issue #7641 has been made to address it