add release process

[jburel]

Add common file for release process of python package
cc @manics

[sbesson]

From the earlier discussion about the docs, I was also wondering whether this page alongside other content currently under https://docs.openmicroscopy.org/contributing/ should be migrated to this organization-wide community health repository.

Two generic questions about this approach:

• are we creating custom filenames as proposed in 05c5a6e or trying to embed this information into a defined community health file type? From https://docs.github.com/en/free-pro-team@latest/github/building-a-strong-community/creating-a-default-community-health-file#supported-file-types, CONTRIBUTING.md is probably the most relevant one to the release process. The main advantage is that it is discoverable from all downstream repositories. The primary downside is that we might want to differentiate contributions from release/maintenance.
• for managing multiple languages/types of repositories, is it preferable to have N files or one files with N sections?

[manics]

I was also going to suggest renaming this file to CONTRIBUTING.md, but then I realised it'll appear on all repos, not just the Python ones.

Separately, do you want to use this issue to discuss bump-version vs setuptools-scm? Or deal with that elsewhere?

[sbesson]

I was also going to suggest renaming this file to CONTRIBUTING.md, but then I realised it'll appear on all repos, not just the Python ones.

Agreed, if we were going for CONTRIBUTING.md, this would definitely involve one section per language and probably a table of content to ease the navigation.

[jburel]

CONTRIBUTING.md is the most suitable options. Having n files might be easier for people when checking but at the same time we might end up with a collection of files. Having a release process header with sub-section: python repo etc. will work.

[jburel]

@manics having a reference file is the first step, so we can link it from the README
then we can decide which tool we wish to use.

[joshmoore]

but then I realised it'll appear on all repos, not just the Python ones.

Though you can override it in subrepositories.

[joshmoore]

Status, @jburel ?

[jburel]

No final decision was made.
Note from ome/omero-web#334 could be added to this change then roll out to all repositories using bump2version since only improvements to the doc were made to omero-web

[will-moore]

What should I do with the changes at ome/omero-web#334?
Open a PR against this branch?
Is this PR otherwise good to merge? "No final decision was made."

Maybe we should merge this and see how it behaves. Will it be visible in other repos if they already have CONTRIBUTING.md? Do we need to delete CONTRIBUTING.md from other repos?
Existing files have info that is not included in this PR: e.g. https://github.com/ome/openmicroscopy/blob/develop/CONTRIBUTING.md

In the meantime I'll keep using ome/omero-web#334 as my release reference.

[joshmoore]

Do we need to delete CONTRIBUTING.md from other repos?

More specific files will override this one, so we may want to point to details here from there.

[sbesson]

Coming back to this issue as I am facing a similar issue while trying to capture the recent release improvements to the omero-* Java components.

Trying to summarize my current understanding of te requirements:

• for maintainers, the natural location for finding information about the release process is in the source code repositories
• for projects with many repositories and many release processes/languages like OME, the duplication and maintenance of individual files across repositories is definitely an issue
• the CONTRIBUTING.md file in the .github repository applies to all repositories unless overriden. This possibly speaks for keeping it fairly generic

On additional thought is that CONTRIBUTING.md is by essence targetting towards code contributions with important information about the formatting/style guide rules, testing & review process. This probably speaks for keeping the documentation aimed at maintainers separate from CONTRIBUTING.md. At the repository level, a section of the README is quite standard as mentioned above. Several projects also use a top-level RELEASE.md file.

Regarding the centralization of the content, we currently have some maintainer level documentation for several classes of components under https://ome-contributing.readthedocs.io. In the absence of a better consensus, I will start using this as a starting point for the OMERO Java components. Happy to migrate the content elsewhere if we build a consensus on a more suitable location.

[jburel]

As discussed, https://ome-contributing.readthedocs.io/ is a good starting point and it will be immediately available in rtd

[sbesson]

See ome/ome-contributing#7