Docs: improve the "Contributing" section documentation

[saragerion]

Description of the improvement

Summary of the proposal

Right now the contributing docs are very bare.
To make it inclusive and accessible for contributors from different seniority, background and experience, this area should be be more detailed to make sure that ambiguity is reduced and most importantly, in case of PR's, expectations are communicated early on in the PR progress.

How, where did you look for information

In the current Contributing doc.

Missing or unclear documentation

Contributions may be related to:

• Design (UX, accessibility)
• Research to scope requirements or understand priorities
• Improve the documentation
• Add or improve examples
• Writing tutorials
• Implementation of new features via Pull Requests's
• Bux fixes
• Share ideas & proposals
• Organising Github issues, labels, projects
• Review code and Pull Requests

Improvement

Rather than 1 single cluttered CONTRIBUITING.md file, a folder with organized files/sections might be easier to read and browse.

Related existing documentation

Contributing file

Related issues, RFCs

#426
#422

[dreamorosi]

Agree that it needs improvement. The AWS Solutions Constructs repo, in my opinion, has a good example of this file.

Also interesting is their DESIGN_GUIDELINES.md file which we could also adopt a form of.

The process they request contributors to follow requires an issue and a design document to be reviewed by a maintainer before someone starts to implement a change. For trivial changes just the issue could suffice but for bigger changes I think it's a good idea. On one hand the maintainer review could become a bottleneck but in the spirit of a good experience as a contributor it'd be far worse to invest time and effort in an implementation that'd be rejected when it becomes a PR.

[bahrmichael]

I like @dreamorosi's suggestion of the AWS Solutions Constructs example, and think we could get a good first document by using and adapting the example for our repository. I'll be happy to start a draft.

I don't have much experience around design guidance, and am quite new to this project. So for now I'll be passive regarding design guidelines.

[dreamorosi]

I think a good starting point for the design principles could be the tenets described in the Python's version of the project. Other than that I think good principles could be feature parity and consistency with other runtimes.

[saragerion]

@bahrmichael @dreamorosi thanks for your input, I completely agree.

I would also add: in our contributing guidelines we should also clarify how to find Issues, PR's (through the Github projects). Additionally we could define what "ownership" (= assignees) of an issue is and what that means in practice.

Here's my proposal:

1. When someone creates a new Issue, there is no owner assigned because the issue needs to be triaged still (we might or might not implement it for example). To get feedback of the maintainers, we can tag them in the issue's comments to get their input (and/or ping them on slack of course). So the issue has no owner (assignee) yet.
2. Once the issue is triaged and ready to be picked up, 1 or more owners can be assigned in the Assignees section. An owner of an issue has the responsibility of carry it to completion and bring it to the done column.

I myself am guilty of assigning issues to get people's attention so not following what suggested above, by the way. But I realised that this was causing me confusion.

I think documenting this etiquette will bring more clarity about who is working on what in the future. But first we need of course to agree whether this is the best way of working/approach or there are better ways.
What do you think?
cc: @alan-churley

[dreamorosi]

100% agree with this, and it's great to document it so that we all know what's the proper etiquette. To double down on this I think we could codify also how PRs should work. For those I think the current behaviour is that the assignee is the person who opened the PR and is responsible of resolve any comment/request from the reviewers. Reviewers are those who are expected to review the PR and provide feedback/approve/reject the changes.

What do you think?

[bahrmichael]

We should also include build steps they can run themselves to ensure proper linting (and maybe add a step in the PR build to verify if it's alright).

Agree on enforcing it.
Using camel casing is something we could also document here #115 because I can see how someone new to the project could do a similar thing.

#102 (comment)

I think we're reaching a point where we need to recollect all the ideas, and trim them down into individual tasks.

[saragerion]

Another item we could document: testing style.
#102 (comment)

[alan-churley]

I think the approach here seems sensible, and yes more documentation on how things should work the better!