contributing: Start pointing people at github

[imp]

Summary

Start pointing people to submitting github pull requests for simple changes.

Sponsored by: Netflix

[imp]

one more nit

[imp]

more tweaks, submitting this one..

[allanjude]

Reviewed by: allanjude

[imp]

Add two points:

(1) You must not use the github fake address
(2) misdirected patches may be redirected for a better resoltuion.

[debdrup]

Just a few nits that I noticed that may be worth considering.

documentation/content/en/articles/contributing/_index.adoc

150

Surely this isn't only limited to the src repo?

158

Should it be explicitly pointed out that it should be the author section that should be correct?

[imp]

documentation/content/en/articles/contributing/_index.adoc

150

Surely it is, at the moment. I have resources lined up for the src repo to make sure we review things in a timely manner. Those resources aren't (yet) present for ports or docs. Since this is a continuation of my github pull request experiment, I thought it best to limit it, for now, to src and gather more data.

158

hmmm, possibly. This is a common problem, but there's no other way to mark them..

All commits must have an author with your name and email address...

might be clearer.

[imp]

be more explicit about author, and collapse 2 points into one.

[freebsd_igalic.co]

documentation/content/en/articles/contributing/_index.adoc

150

issues aren't automatically closed. they are closed, period.
it's not possible to submit issues on the src repo

[imp]

Remove comment about issues (they can't be created)
minor word smithing

[debdrup]

Looks good to me!

[mhorne]

These are great guidelines.

As a related, but tangential improvement, I would suggest creating a small PR template in the src repo that points to this page/section. This makes it more discoverable. Having the guidelines linked/listed when creating a new PR allows us to more easily justify immediate rejection of PRs that don't follow them ("you didn't read the instructions").

https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository

[freebsd_igalic.co]

and/or

In D38382#872773, @mhorne wrote:

These are great guidelines.

As a related, but tangential improvement, I would suggest creating a small PR template in the src repo that points to this page/section. This makes it more discoverable. Having the guidelines linked/listed when creating a new PR allows us to more easily justify immediate rejection of PRs that don't follow them ("you didn't read the instructions").

https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository

a CONTRIBUTING.md at the base of the repo

[imp]

Add note about ports pull requests.
Emphasize that 'fixup' commits should be squashed.

[imp]

In D38382#872773, @mhorne wrote:

These are great guidelines.

As a related, but tangential improvement, I would suggest creating a small PR template in the src repo that points to this page/section. This makes it more discoverable. Having the guidelines linked/listed when creating a new PR allows us to more easily justify immediate rejection of PRs that don't follow them ("you didn't read the instructions").

https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository

Since that's in a separate repo, I'll have to do a separate review. I love the suggestion...

[imp]

In D38382#872800, @freebsd_igalic.co wrote:

and/or

In D38382#872773, @mhorne wrote:

These are great guidelines.

As a related, but tangential improvement, I would suggest creating a small PR template in the src repo that points to this page/section. This makes it more discoverable. Having the guidelines linked/listed when creating a new PR allows us to more easily justify immediate rejection of PRs that don't follow them ("you didn't read the instructions").

https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository

a CONTRIBUTING.md at the base of the repo

Also a good idea... Most likely, though, it will be a brief note pointing people to our other docs which are more likely to be up to date.

[ceri]

documentation/content/en/articles/contributing/_index.adoc

164

manage

[imp]

Fix spelling. Add quick note that docs repo hasn't established any policy yet.

[imp]

add so for emaste

[imp]

documentation/content/en/articles/contributing/_index.adoc

150

I also added information about doc and ports @debdrup since they haven't yet committed to any SLA on pull request...

[grahamperrin]

GitHub (not github).

documentation/content/en/articles/contributing/_index.adoc

150

The link is to the pull requests part of the mirror.

154

171

[emaste]

Overall LGTM modulo the few nits

[imp]

GitHub

[brooks]

I generally like the text and @imp has included my feedback from prior versions.

[grahamperrin]

documentation/content/en/articles/contributing/_index.adoc

157

158

The second sentence can be shorter, or removed.

(The requirement for a valid (non-fake) address is in the first sentence.)

161

161

163

165

168

176

Re: https://wiki.freebsd.org/Bugzilla/DosAndDonts this type of summary line tag is deprecated.

[grahamperrin]

documentation/content/en/articles/contributing/_index.adoc

159–161

Do these three list items truly belong under the leading sentence?

A patch is simple if:

[imp]

Thanks for the feedback... I've updated things...

documentation/content/en/articles/contributing/_index.adoc

157

After dealing with about 200 pull requests, I think that we should be more explicit here, rather than more spartan with our phrasing.

158

I like the shorter way you put the second sentence, but I think it should stay for emphasis. A big issue on the pull requests I've done to date has been nagging people to redo the commits with a real email. Plus, the project allows pseudonyms for submissions.... I've reworded to try to make it better....

161

I like the bullet list as it is, but maybe there's a better way to introduce it.

"Ideal patches are as follows:"

maybe?

163

I came up with a shorter alternative...

165

I like this, but came up with something a little shorter too...

168

How else do I convey that it's basically a crap shoot if you submit a ports pull request?

176

This is a separate issue. Honestly, this whole section needs to be revamped. but part of the revamp may hinge on how successful this experiment is... Feel free to do this yourself... But I'm not sure about that wiki... some of the ideas don't seem to match other policy very well...

[imp]

update based on feedback to wordsmith