docs(contributors): update contributors workflow (#15)

Author: uniqueg

docs/guides/guide-contributor/workflow.md

@@ -5,15 +5,16 @@ To start working with us, please follow these simple steps:
 1. Join [:custom-github-black: GitHub][github-join].
 2. Check out our [repositories][elixir-cloud-aai-github] and [open
    issues][elixir-cloud-aai-issues].
-3. Join our [:custom-slack: Slack board][elixir-cloud-aai-slack].
+3. Join our [:custom-slack: Slack board][elixir-cloud-aai-slack] (please [let us
+   know](../../about/contact.md) if the link expired).
 4. Join the [`#oss-community`][elixir-cloud-aai-slack-channel-oss] and leave
    a short message about yourself. Please include (1) your relevant skills and
    experience level, (2) your GitHub username, (3) your email address (e.g.,
    for calendar invitations), and (4) the repositories or issues you are most
    interested in. If you can't decide, no problem, just indicate that you are
    open to work on anything and we will suggest some issues for you.
-5. Once we have added you to our [GitHub
-   organization][elixir-cloud-aai-github], you can assign yourself to an issue.
+5. Once we have added you to our [GitHub organization][elixir-cloud-aai-github],
+   you can assign yourself to an issue.
 6. Please carefully read the [guidelines](#guidelines) below, as well as any
    relevant language-specific guidelines in this section.
 7. Start coding! :computer:
@@ -35,9 +36,10 @@ To start working with us, please follow these simple steps:
 
     If you like, you can skip steps 3. to 5. and raise pull requests from
     forks. Note, however, that some CI workflows may not (yet) be fully
-    supported for pull requests raised from forks.
+    supported for pull requests raised from forks, which may delay the review
+    process and the merging of your changes.
 
-## Guidelines
+## General guidelines
 
 For your contributions, please follow the guidelines laid out below to the best
 of your ability.
@@ -57,7 +59,9 @@ of your ability.
 Please use the comment functions available on GitHub to discuss issues and
 pull requests. For all other communications please refer to the communication
 channels listed in the [contact](../../about/contact.md) section. In
-particular, use the [chat][elixir-cloud-aai-slack] to discuss project ideas.
+particular, use the [chat][elixir-cloud-aai-slack] to discuss project ideas,
+get help on a problem, or any other informal discussion that does not need to
+be preserved as part of the repository you are working on.
 
 ### Submitting issues
 
@@ -203,29 +207,39 @@ following **type** prefixes:
 **Make sure to follow the [commit message](#commit-messages) rules for your pull
 request titles.**
 
-The following pull request template will be successively added to all
-repositories. Until that is the case, you can already make use of it by
-self-reviewing your pull requests according to the checklist and descriptions.
+#### Code reviews
 
-!!! note "All Contributors"
+All code changes are reviewed by at least one other person. This is to ensure
+that the code is of high quality, that it is well-documented and that it adheres
+to the project's coding standards. The reviewer will check that the code is
+correct, that it is efficient and that it is maintainable. They will also check
+that the code is well-documented and that it is tested.
 
-    The [All Contributors][all-contributors] bot may not be available in all
-    repositories yet. In that case, please ignore the last bullet point.
+Please make sure to actively request reviews for your pull requests to avoid
+delays in the review and merging process. Please use the GitHub functionality
+for that (upper right hand corner of pull request view). If you are unsure who
+to ask for a review, please reach out to the project leads.
 
 #### Pull request template
 
+The following pull request template will be successively added to all
+repositories. Until that is the case, you can already make use of it by
+self-reviewing your pull requests according to the checklist and descriptions.
+
 ##### Description
 
 > Please include a summary of the change and the relevant issue(s) it resolves,
-> if any (otherwise delete that line). If the PR addresses more than one issue,
-> please add multiple lines, each starting with 'Fixes #'. In the summary, list
-> any dependencies that are required for this change. Please use bullet points
-> for the description. Please also include relevant motivation and context
-> briefly if not already covered in the corresponding issue(s). For very
-> trivial issues that are duly explained by the PR title, a description can be
-> omitted (in that case, please delete the placeholder bullet point).
-
-- 
+> if any (otherwise delete that line), e.g., `Fixes #123`. If the PR addresses
+> more than one issue, please add multiple lines, each starting with 'Fixes #'.
+> Please stick to that syntax precisely, including whitespaces, otherwise the
+> issue(s) may not be linked to the PR.
+>
+> In the summary, list any dependencies that are required for this change.
+> Please use bullet points for the description. Please also briefly describe
+> the relevant motivation and context briefly. For very trivial changes that are
+> duly explained by the PR title, a description can be omitted.
+
+-
 
 Fixes #(issue number)
 
@@ -234,12 +248,13 @@ Fixes #(issue number)
 > Please go through the following checklist to ensure that your change is ready
 > for review. Please do not forget to double check the list after you have
 > modified your PR, e.g., if you have added commits to address reviewer
-> comments or to fix failing automated checks. Please check items also if they
-> do not apply to your change, e.g., if your change does not require an update
-> of the user-facing documentation, then still check the box. Generally, PRs
-> are only reviewed when all boxes are ticked off and all automated checks pass
-> (use the comment section below if you believe that your PR is ready to be
-> merged even though not all boxes were ticked off).
+> comments or to fix failing automated checks. **Please check items also if they
+> do not apply to your change**, e.g., if your change does not require an update
+> of the user-facing documentation, still check the box.
+>
+> Generally, **PRs are only reviewed when all boxes are ticked off and all
+> automated checks pass** (use the comment section below if you believe that
+> your PR is ready to be merged even though not all boxes were ticked off).
 
 - [ ] My code follows the [contributing guidelines](workflow.md) of this
       project, including, in particular, with regard to any style guidelines
@@ -253,10 +268,10 @@ Fixes #(issue number)
 - [ ] I have updated the user-facing documentation to describe any new or
       changed behavior
 - [ ] I have added type annotations for all function/class/method interfaces
-      or updated existing ones
+      or updated existing ones (only for Python, TypeScript, etc.)
 - [ ] I have provided appropriate documentation (e.g., [Google-style
       Python docstrings][py-doc-google] or [JSDoc block tags][jsdoc]) for all
-      functions/classes/methods or updated existing ones
+      packages/modules/functions/classes/methods or updated existing ones
 - [ ] My changes generate no new warnings
 - [ ] I have added tests that prove my fix is effective or that my feature
       works
@@ -270,10 +285,122 @@ Fixes #(issue number)
       not want my contributions to be acknowledged by [All
       Contributors][all-contributors]
 
+!!! note "All Contributors"
+
+    The [All Contributors][all-contributors] bot may not be available in all
+    repositories yet. In that case, please ignore the last bullet point.
+
 ##### Comments
 
 > If there are unchecked boxes in the list above, but you would still like your
 > PR to be reviewed or considered for merging, please describe here why boxes
 > were not checked. For example, if you are positive that your commits should
 > _not_ be squased when merging, please explain why you think the PR warrants
-> or requires multiple commits to be added to the history.
+> or requires multiple commits to be added to the history (but note that in
+> that case, it is a prerequisite that all commits follow the Conventional
+> Commits specification).
+
+## Managing your own project
+
+If you are managing a project by yourself or with others, please follow these
+additional guidelines below.
+
+### Community standards
+
+Please try to adhere to best community standards. To help with that, visit
+GitHub's "Community Standards" section (accessible in each repository via the
+"Insights" tab) and confirm that the following are available in the repository
+root directory:
+
+- **README** in file `README.md`
+- **Code of Conduct** in file `CODE_OF_CONDUCT.md` (can link to the [Code of
+  Conduct](../../about/code-of-conduct.md) on this page)
+- **Contributing guidelines** in file `CONTRIBUTING.md` (can link to the
+  [contributor guide](../index.md) on this page)
+- **License** in file `LICENSE`)
+- **Pull request template** in file `PULL_REQUEST_TEMPLATE.md`
+
+Also make sure that a project **description** (right hand panel on the
+repository's main page) and one or more **issue templates** (in
+`.github/ISSUE_TEMPLATE`) are available.
+
+### Licensing
+
+All projects must be licensed under an [Open Source Initiative
+(OSI)][osi]-approved license. The license must be included in the repository
+root directory in a file named `LICENSE`. Unless otherwise discussed, please
+use the [Apache License 2.0][license-apache].
+
+### Versioning
+
+All our projects are versioned according to the [Semantic Versioning][sem-ver]
+specification. This means that each version number consists of three parts:
+`MAJOR.MINOR.PATCH`. The version number is increased as follows:
+
+- `MAJOR` version is increased when you make incompatible/breaking API changes
+- `MINOR` version is increased when you add functionality in a backwards
+  compatible manner
+- `PATCH` version is increased when you make backwards compatible bug fixes
+
+Note that projects in pre-release state, i.e., should be assigned a version
+number below `1.0.0` (start with `0.1.0`). In Semantic Versioning, this means
+that API changes can occur at any moment, which is suitable for a project that
+has not reached sufficient maturity and API stability yet.
+
+### Continuous Integration
+
+We are fully embracing the concept of continuous integration (CI) and related
+practices. This means that all code changes are automatically tested and
+validated before they are merged into the main codebase. This is to ensure that
+the codebase remains stable and that new features and bug fixes do not break
+existing functionality.
+
+Therefore, when starting a new project, as soon as possible, please add one or
+more GitHub Actions workflows to your project that do the following for pushes
+to and pull requests against the repository's default branch (see existing
+projects for examples):
+
+- Run linting and formatting checks
+- Run type checks (if applicable)
+- Run unit and integration tests
+- Check test coverage and upload results to [Codecov][codecov]
+- Build and publish documentation (if not set up to be triggered automatically
+  by the publishing system, e.g., Read the Docs)
+
+!!! note "Continuous Delivery/Deployment"
+
+    If the project you are working on is reasonably mature, also consider
+    setting up one or more continuous delivery/deployment workflows.
+
+### Documentation
+
+Related to continuous integration, we also value continuous documentation. This
+means that documentation is updated and improved as the codebase evolves. This
+is to ensure that the documentation remains accurate and up-to-date and that it
+reflects the current state of the codebase. It also means that we want to start
+writing documentation as early as possible.
+
+Currently, we are using Markdown to write documentation. For new projects, we
+expect that each project has a `README.md` file that covers the following
+sections (fill in with "Coming soon" if not yet available):
+
+- **Synopsis**: A brief description of the project
+- **Basic usage**: A brief overview of how to use the project
+- **Installation**: Instructions on how to install/deploy the project
+- **Versioning**: Information on how the project is versioned
+- **Contributing**: Guidelines on how to contribute to the project, with links
+    to the [contributing guidelines](../index.md) and our
+    [code of conduct](../../about/code-of-conduct.md)
+- **Contact**: Information on how to contact the project leads
+
+#### Hosted documentation
+
+As projects grow, a simple `README.md` will not be sufficient anymore.
+
+We therefore kindly ask you to prepare a dedicated, hosted documentation page
+early on. This can be done using services like [Read the Docs][read-the-docs] or
+GitHub Pages with MKDocs (like this page).
+
+Carefully consider the audiences for your project and tailor the documentation
+accordingly. In all cases, we expect that API documentation is made available
+(can be auto-generated from code, e.g., via [Sphinx][sphinx]).

includes/references.md

@@ -7,6 +7,7 @@
 [bh-elixir]: <https://www.biohackathon-europe.org/>
 [bh-mena]: <https://cbrcconferences.kaust.edu.sa/bio-hackathon-2023>
 [cephfs]: <https://docs.ceph.com/en/quincy/cephfs/>
+[codecov]: <https://codecov.io/>
 [contributor-covenant]: <https://www.contributor-covenant.org>
 [conv-commits]: <https://www.conventionalcommits.org/en/v1.0.0-beta.2/#specification>
 [conv-commits-blog]: <https://nitayneeman.com/posts/understanding-semantic-commit-messages-using-git-and-angular/>
@@ -81,6 +82,7 @@
 [k8s-jobs]: <https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion>
 [k8s-pvc]: <https://kubernetes.io/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims>
 [k8s-storage-class]: <https://kubernetes.io/docs/concepts/storage/storage-classes/>
+[license-apache]: <https://www.apache.org/licenses/LICENSE-2.0>
 [linkedin-akash]: <https://www.linkedin.com/in/akash-saini-ak7778/>
 [linkedin-anurag]: <https://www.linkedin.com/in/anurag-gupta-1201/>
 [linkedin-assel]: <https://www.linkedin.com/in/assel-abzalova/>
@@ -96,14 +98,14 @@
 [minio]: <https://min.io/>
 [minio-deploy-openshift-template]: <https://github.com/CSCfi/Minio-OpenShift>
 [minio-docs-k8s]: <https://min.io/docs/minio/kubernetes/upstream/index.html>
+[mkdocs]: <https://www.mkdocs.org/>
 [nextflow]: <https://www.nextflow.io/>
 [netrc]: <https://www.gnu.org/software/inetutils/manual/html_node/The-_002enetrc-file.html>
 [nfs]: <https://en.wikipedia.org/wiki/Network_File_System>
 [openpbs]: <https://www.openpbs.org/>
 [openshift]: <https://www.redhat.com/en/technologies/cloud-computing/openshift>
 [osi]: <https://opensource.org/>
 [py]: <https://www.python.org/>
-[py-codecov]: <https://codecov.io/>
 [py-cov]: <https://github.com/nedbat/coveragepy>
 [py-doc-google]: <https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html>
 [py-downloads]: <https://www.python.org/downloads/>
@@ -121,6 +123,7 @@
 [slurm]: <https://slurm.schedmd.com/>
 [snakemake]: <https://snakemake.readthedocs.io/en/stable/>
 [snakemake-docs]: <https://snakemake.readthedocs.io/en/stable/executing/cloud.html#executing-a-snakemake-workflow-via-ga4gh-tes>
+[sphinx]: <https://www.sphinx-doc.org/en/master/>
 [tesk]: <https://github.com/elixir-cloud-aai/TESK>
 [tesk-docs-deploy]: <https://github.com/elixir-cloud-aai/TESK/blob/master/charts/tesk/README.md>
 [tesk-docs-deploy-values]: <https://github.com/elixir-cloud-aai/TESK/tree/master/charts/tesk#description-of-values>