Contributor's Guide : Release Workflow : Explanation of how releases are compiled and how tagging is used

[almereyda]

The Contributor's Guide has a description of artifacts and common workflows around the development of the application and its plugins. While the overall release process of the application is left implicit there, we can find a series of tags next to the repository and a separate documentation page of how to release a plugin into the plugin gallery.

As a Software engineer in the PKP ecosystem, I need a written description about conventions and practices used to build and release the software, in so I am rendered more capable to contribute with less friction.

As a systems engineer taking and deploying components from the PKP ecosystem, I need a conventional way to reproduce Software artifacts, in order to ensure reproducibility and deterministic execution of code paths.

Related to this, due to terminology used which is local to the PKP development community, it is quite hard to find the changelog which informs about breaking changes and added features. A curious reader will find their way around to the Release Notebooks, but the section in the Contributor's guide doesn't link there and the common term Changelog is nowhere to be found on that page nor the other(s), neither with search.

Explicitly stating the practices used to build releases increases the trust in the procedure and allows others to replicate it more easily, inviting for more collaboration. In addition, making links between content explicit can render it more accessible/navigable and reusing conventional language lowers the entry barrier for non-native speakers by sacrificing semantic specificity for syntactic simplicity.

Ultimately, the Contributor's guide holds information about the branching convention, but no obvious explanation how tags are chosen and published plus subsequently compiled into a release. Whereas on the other hand the procedure to Release a Plugin has mentions of versions, but no reference to tagging, branches or a typical development-release-workflow.

Could we coordinate a little around updating the documentation with some details about the release processes, in so working with the code bases of the application and its plugins becomes more expectable?

[almereyda]

A fun and visual way to document some of these procedures could be to leverage Mermaid's gitGraph. Please take these sketches as inspiration, as they do not convey any specific meaning without their context:

---
title: |
  Branching model with release tracking branches
---
%%{init: { 'logLevel': 'info', 'theme': 'base', 'gitGraph': {'mainBranchName': 'stable-3_3_0'}} }%%
gitGraph
  commit id:"…"
  commit id:"Merge feat/issue-123 into stable-3_3_0"
  commit id:"Merge feat/issue-127 into stable-3_3_0"
  branch feat/issue-130
  commit
  commit
  checkout stable-3_3_0
  merge feat/issue-130 id:"Merge feat/issue-130 into stable-3_3_0"

Loading

---
title: |
  Branching model with main always healthy and deployable
---
gitGraph
  commit id: "…"
  commit id: "Merge feat/issue-123 into main" tag: "v0.1.0"
  commit id: "Merge feat/issue-127 into main"
  branch feat/issue-130
  commit
  commit
  checkout main
  merge feat/issue-130 id: "Merge feat/issue-130 into main" tag: "v0.3.0"

Loading