suggest edit feature: add link to contributor instructions

[jenniferfell]

I'm submitting a...

[ ] Regression (a behavior that used to work and stopped working in a new release)
[ ] Bug report  
[ ] Performance issue
[ ] Feature request
[X ] Documentation issue or request
[ ] Support request => Please do not submit support request here, instead see https://github.com/angular/angular/blob/master/CONTRIBUTING.md#question
[ X] Other... Please describe: docs-infra

Current behavior

Suggest Edits (pencil on the API reference pages) directly opens an editing window with controls to quickly create a PR with the suggested change. This is great for repeat contributors. It does not help new contributors sufficiently.

Expected behavior

Editing window has a link to contributor instructions (currently contributing.md) that explain important things, such as the need to sign the CLA, the overall PR review and acceptance process, commit message guidelines, etc.

Minimal reproduction of the problem with instructions

1. Go to any API reference page
2. Click the Suggest Edits pencil icon upper right.
3. Look for any instructions.

What is the motivation / use case for changing the behavior?

Support new or infrequent contributors better.

Environment

Angular version: X.Y.Z


Browser:
- [ ] Chrome (desktop) version XX
- [ ] Chrome (Android) version XX
- [ ] Chrome (iOS) version XX
- [ ] Firefox version XX
- [ ] Safari (desktop) version XX
- [ ] Safari (iOS) version XX
- [ ] IE version XX
- [ ] Edge version XX
 
For Tooling issues:
- Node version: XX  
- Platform:  

Others:

[IgorMinar]

#25764 implemented this, but at the cost of losing the information about what file to edit and ability to open the github editor with that file loaded. This is an unacceptable trade off because now even though I was told how to contribute, I don't know what file to edit.

I think we still want contributors to be able to go the the editor with little friction, because that's how they can determine if they can and want to contribute anything at all.

Ideally we'd want the contributor to have an option to read through the contribution docs as they open the editor. Most contributors will ignore the docs and just propose a change, at which point it's up to the CI to steer the contributor in the right direction (like sign CLA).

But realistically, many simple contributions, especially those made via the github editor (like typo fixes) will be just "thrown over the fence" to us and the contributors won't be following up on them any more. So it will be up to us to either abandon such PR, recreate it, or if CLA was signed, update it and get it into a mergeable state ourselves.

Historically we've been more successful at getting followups on PRs when the contributors got immediate and actionable feedback from the CI. This is because they were still engaged and haven't context switched.

I believe @manughub asked GitHub for an ability to add contribution instructions into the editor flow, that would help. If that doesn't happen these are other options:

1. we can either improve the CI response by providing better messaging when issues in a PR are found.

2. we could include a comment with a link to the contribution instructions in every .ts and .md file at the top, so that when the github editor opens it, the instructions would be right there.

3. we could build a special page on angular.io with contributor instructions that keeps the information about the edit url and the page would also contain "Continue to editing" button that would then activate the stored edit url.

I'm not a big fan of #3 because it will scare people away, affect repeat contribution flow, and won't intercept the contribution flow that doesn't come via the angular.io edit icon.

After thinking through all these options maybe #2 would be the best? We would add a comment to the top of the existing md files and expand the current copyright header in all the .ts files to include contribution instructions. What do you think?

[manughub]

@IgorMinar I reached out to Will re getting gitHub to show contribution instructions in the editor workflow. He is out till Sep 6 and I'll ping him upon his return.

[gkalpak]

I think integrating it into GitHub would be the best option.
Another option (that's similar to #3) would be:

• When you click the "edit" button, we open a modal with something like:

  You are about to edit "blah/blah.md". If this is your first time contributing to Angular, you might want to check out our contribution guidelines. Click here to open the guidelines in a new page.

  • Do not show again.

  Got it, let me edit the file

• Clicking the link to contribution guidelines, opens CONTRIBUTING.md in a new page (so they don't lose context) and they can come back to them later (e.g. when they are about to enter the commit message).

• Checking the Do not show again checkbox, we can store this preference (same as we do not notification campaigns) and not bother them again, thus not affecting repeated contribution flow.

• Finally clicking the "Got it" button proceeds as usual (taking them to GitHub).

[ajitsinghkaler]

@gkalpak should I try to implement this modal

[gkalpak]

This is a non-trivial change, both in terms of implementation and in terms of UX, so we should first get consensus. (Keep in mind that this is a relatively low priority issue.)

cc @IgorMinar, @petebacondarwin, @aikidave, @kapunahelewong, @sjtrimble

[angular-automatic-lock-bot]

This issue has been automatically locked due to inactivity.
Please file a new issue if you are encountering a similar or related problem.

Read more about our automatic conversation locking policy.

_{This action has been performed automatically by a bot.}