Create CONTRIBUTING.md

[stevepiercy]

Is your feature request related to a problem? Please describe.

New users frequently ask how to contribute to Volto, and I do not know the authoritative location for that.

I think we use the following:

• https://github.com/plone/volto#volto-development
• https://6.dev-docs.plone.org/volto/developer-guidelines/index.html
• https://6.dev-docs.plone.org/volto/contributing/guidelines.html

The last two are way confusing. 😕 See screenshot as rendered in Documentation:

The standard is to have a CONTRIBUTING.md file at the root of a project. GitHub uses a repo's CONTRIBUTING.md when new users open an issue or pull request for the first time, and this would help guide them to be more successful. This does not happen currently in Volto because we lack a CONTRIBUTING.md.

Describe the solution you'd like

We have a default CONTRIBUTING.md for the Plone organization, but that is insufficient.

We should have a local CONTRIBUTING.md in the repo that overrides the organization level file. That file should be placed in the root of the project (that's where developers look first), or alternatively in .github/.

We should then add a file in the Volto documentation that includes the new CONTRIBUTING.md.

Finally, we would need to update the Makefile in Documentation to clone the root of the Volto repo, instead of just its documentation, so that we can properly pull in the file and build the entire documentation.

I would appreciate your thoughts and feedback on this.

[stevepiercy]

From @ksuess in #3934 (comment):

I think this belongs to "Contributing". May I suggest to name a main navigation item "Contributing".

Then "Contributing" is the link that can be posted if there is a need to clarify where to target, which branch, what the piep is canary, what means stable, ....

"Developer guidelines" is for both: "understand Volto and make your thing" and also "understand Volto to contribute to Volto".

I would like to suggest to move "Dev guidelines" in navigation just after " dev recipes".

[stevepiercy]

Update

1. We now have a Volto CONTRIBUTING.md. This consists of a file that points to Contributing to Volto.
2. https://6.docs.plone.org/volto/contributing/guidelines.html was removed in Docs: Clean up "design principles" and "contributing" #3643 followed by some clean up in Bring back "Guidelines for Contributing" #3644.

Next steps

• Review, approve, merge PR Update Volto contributing to align with and refer to the new Plone co… #4634.
• Promote developer-guidelines/contributing.md to the top level navigation at contributing/index.md.
• Update link in CONTRIBUTING.md to point to the new location.
• Update https://6.docs.plone.org/volto/developer-guidelines/contributing.html with:
  • how to assign yourself to an issue and don't ask to be assigned or to work on an issue. Check for a linked PR or someone already assigned. See Add option to add action button to the top of the toolbar and menu button to the bottom of the toolbar. #4333 (comment) [EDIT: Now exists in First-time contributors]
  • Mention PLIPs https://5.docs.plone.org/develop/coredev/docs/plips.html [EDIT: This will be done in https://github.com/Migrate buildout.coredev docs into Plone 6 Documentation documentation#1486 ]
  • Mention contributing in main docs. See Edit Contributing docs documentation#1278 and buildout.coredev docs need to be pulled into Plone 6 Documentation buildout.coredev#840

I would like to get the opinions of @plone/volto-team before doing any work.

[davisagli]

@stevepiercy I think a lot of this was addressed by plone/documentation#1478 and #4634. Is there any part left to do or can we close the issue?

[stevepiercy]

I updated the checklist. There is still some work to perform.

[stevepiercy]

Actually this issue is a mess. I have a better idea. Closing in favor of #4665