[docs]: Updates to contribution guidelines

[saehejkang]

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update

Motivation and Context

• Added an index to the doc for easily accessing important sections
• Added two new main sections to help first time contributors with tips on how to get started with issues, how to ask for help, and who to ask for help.
• Made all headings sentence case for consistency

Closes apple/container#880, as it was preferred to not add a CODEOWNERS file, but instead add notes to where contributors can find a list of maintainers to ping.

Testing

• Tested locally
• Added/updated tests
• Added/updated docs

[katiewasnothere]

Sorry for the delay. I think we've sorted out what we want to do about the list of people you can ping (PRs coming for that).

For more feedback on this PR, with these changes, CONTRIBUTING has both direct policies (like the AI policy, Code of Conduct, etc) AND kind of "soft" policies like "here's when it's reasonable to ping someone to help move along your PR". I was thinking maybe we put the soft policies on how to pick an issue, how to get help, etc in a separate doc and link to it from CONTRIBUTING.

What do you think? Definitely open to more discussion here. The concern I think I have with what this PR is adding right now is that it makes it harder for people who are seasoned contributors to open source to find the hard policies for the repo, which may make them less likely to read the doc at all.

[saehejkang]

I think we've sorted out what we want to do about the list of people you can ping (PRs coming for that).

🚀

What do you think? Definitely open to more discussion here.

My only qualm with this is that there are other policies (submitting issues, pull requests), in the contribution file, that I feel are really helpful. Should those not also be moved then?

is that it makes it harder for people who are seasoned contributors to open source to find the hard policies for the repo, which may make them less likely to read the doc at all

Not sure what you mean by this 🤔. I would think that new/seasoned contributors would route to the contribution guide on first glance and see both the direct/soft policies?

in a separate doc and link to it from CONTRIBUTING

What would you want to name this file, if we went this direction?

[katiewasnothere]

@saehejkang Yeah that's a valid concern. It does feel weird to have two locations for policies. Another option I was thinking about was having the contributing doc structured like this:

• index for different sections
• Separate sections for "New to git?", "New to GitHub?", and "New to apple/container/ization"

Then people can navigate just to the sections that are relevant to them. If they've never used git or made open source contributions, they would read the whole thing. If they're seasoned contributors to other oss projects, they can skip down to "New to apple/container/ization". We'd have the "how to pick an issue", "when/how to get help" and similar subsections under the "New to Github" section imo but we can discuss more.

What do you think?

[saehejkang]

What do you think?

I like the idea of adding an index for different sections. Thoughts on naming the section "New to open source"? I feel all the policies below are fair guidelines that open source contributors should know about before contributing to any repo. If need be, the "who to ask for help" section can be moved under "New to apple/containerization", as that list is specific to the repo.

• how to get started with issues
• how to ask for help
• who to ask for help

[katiewasnothere]

@saehejkang That sounds good to me! Thanks for working on this :)

[saehejkang]

@katiewasnothere I will be out of town starting this Friday (12/12). Let me know if you need anything else from me, so we can get this merged here soon.

[katiewasnothere]

Suggested change

	It's possible that you ask someone a question in a issue/pull request and
	you don't get a response as quickly as you'd like. If you don't get a response
	within a week, it's okay to politely ping them using an `@` mention with a
	reminder. If you don't get a response for 2-3 weeks in a row, please ping
	someone else.
	It's possible that you ask someone a question in an issue/pull request and you don't get a response as quickly as you'd like. If you don't get a response within a week, it's okay to politely ping them using an `@` mention. If you don't get a response for 2-3 weeks in a row, please ping someone else.

[realrajaryan]

this question/bullet is redundant and too prescriptive tbh, shouldn't have to be spelled out

[saehejkang]

I disagree. Laying out a timeline for contributors to follow when using an @, will alleviate noise in the maintainers inboxes. This can go one of two ways:

• If a contributor is afraid to ping someone multiple times, they will know it is polite/okay to do so.
• If a contributor tends to keep asking the same person for help, they know that they should ping someone new

[katiewasnothere]

@saehejkang Thanks for letting me know! Will try to prioritize this today so we can get this in!

[realrajaryan]

I don't see a reason to switch away from Title Casing for the topic headers, let's revert these to how they were previously so we don't add unnecessary diff

[saehejkang]

This update was for consistency based on what I saw in both projects (docs, readmes, etc.). I would prefer to keep these changes as they are very minimal.