implement frequent releases with semver

[altergui]

we want to adopt semver for releases, to minimize interop issues. my understanding would be:

• [ ] reduce the friction of making vocdoni-node releases to a minimum (a git tag, ideally? the changelog being the commit messages)
• [ ] make the CI push docker images to the corresponding tag
• [ ] implement gitflow branch system (PRs against "dev", and infrequent merges from dev to "stage" and then to "main" branch)

some references: https://www.notion.so/aragonorg/QA-first-iteration-99f6a78eb44649a4955cdd9e49e6516d#4c815bb475444fb09e33248ec4c4a5db https://gitlab.com/vocdoni/go-dvote/-/wikis/Git-branching-and-guideline

a somehow related issue: "Define and implement BuildInfo page or endpoint for Vocdoni and Aragon applications" https://aragonassociation.atlassian.net/browse/DOPS-462

[altergui]

until now, we had infrequent releases with codenames (azeno, next bizono) and no semantic versioning azeno had a tagged release https://github.com/vocdoni/vocdoni-node/releases/tag/v1.3.0 and there's also a branch named release-azeno which after that v1.3.0 tag grew with 4 commits back in december, but not tagged into any release yet (for example v1.4.0) https://github.com/vocdoni/vocdoni-node/compare/master...release-azeno

[altergui]

until now, how we dealt with branches:

master

• default branch in github (i.e. git clone https://github.com/vocdoni/vocdoni-node pulls master)
• all PRs are made against master branch
• master branch is protected against direct pushes, only merges of reviewed PRs are allowed.
• whenever a commit is pushed to master (i.e. a reviewed PRs is merged), CI builds a docker image and pushes it both to https://hub.docker.com/r/vocdoni/go-dvote and https://ghcr.io
  • actually, two images are built, one intended for production and one built with -race.
  • the non-race image gets two tags "permanently":
    • master-$(date +%s) (for example master-1680260490)
    • commit-$(git rev-parse --short HEAD) (for example commit-e998ea5)
  • same goes for -race image:
    • master-race-1680260490
    • commit-race-e998ea5 (actually main.yml is buggy and commit-e998ea5 gets overwritten :facepalm:)
  • and the "moving" tags get updated:
    • latest and latest-race
    • master and master-race

(i'm so glad i'm writing this proposal, that includes ditching the master branch, especially after seeing that master-race tag :facepalm: )

dev

• dev branch is updated sometimes, at the will of some developer. normally the update means pointing dev to the same commit as master. Then master will continue growing and dev will be left behind.
• docker images are built and pushed in the same fashion as master branch, every time a commit is pushed to dev branch
• dev branch is automatically deployed to https://api-dev.vocdoni.net (using containrrr/watchtower)
• dev environment is intented to be used only internally in vocdoni. it might break any time without notice. no external user, developer or integrator hits https://api-dev.vocdoni.net.

  stage

• stage branch is updated sometimes, at the will of some developer. normally the update means pointing stage to the same commit as master. Then master will continue growing and stage will be left behind.
• docker images are built and pushed in the same fashion as master branch, every time a commit is pushed to stage branch, but without -race images.
• stage branch is automatically deployed to https://api-stg.vocdoni.net (using containrrr/watchtower)
• stage environment is intended to be used by external developers (for example integrators). they are given notice whenever that environment is updated (branch updated, hosts redeployed), especially when that involves breaking changes. Not intended for production.

[altergui]

Proposal 1

all in all, the way we handle branches until now is aligned with "Trunk Based Development" https://www.atlassian.com/continuous-delivery/continuous-integration/trunk-based-development so i'd propose to simply rename master to main but tagging more frequent releases, possibly on a weekly basis, following semantic versioning.

so for example dcf2e8ef304aba27c79207c48d471a2fe0a8deab would have been tagged as v1.4.0 at the end of the day 6a3f36619dd0bad665e505eb669a95c214b03819 v1.5.0 74174190df2a10da73f461b8e88102ec637eb5a1 v1.5.1 7d2869629afbf07ac1d71675f267ecfd99ccc869 v1.5.2 c70a8408330185b46151ca2ede204359b92de1e8 and 7700b9a34a12afccd04dc2f5f00905b95c8b9095 would not trigger a release since it's internal refactoring, no fix or feature. 6095f229cd59952ad9a7e0f1d444ed712a429893 v1.6.0

Proposal 2

change our branching model to follow gitflow https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow not necessarily a good idea: "Gitflow is a legacy Git workflow that was originally a disruptive and novel strategy for managing Git branches. Gitflow has fallen in popularity in favor of trunk-based workflows, which are now considered best practices for modern continuous software development and DevOps practices"

nvie also commented on the original post: Web apps are typically continuously delivered, not rolled back, and you don't have to support multiple versions of the software running in the wild. This is not the class of software that I had in mind when I wrote the blog post 10 years ago. If your team is doing continuous delivery of software, I would suggest to adopt a much simpler workflow (like GitHub flow) instead of trying to shoehorn git-flow into your team.

[altergui]

explorer follows an equivalent branching model:

• main branch is where development PRs are merged.
  • continuously deployed to https://dev.explorer.vote/
  • behind the scenes, hits https://api-dev.vocdoni.io/v2/
• stage branch is updated on-demand, following master.
  • continuously deployed to https://stg.explorer.vote/
  • behind the scenes, hits https://api-stg.vocdoni.io/v2/
• release-azeno branch stems off master and grows independently.
  • deployed (continuously?) to https://explorer.vote/
  • behind the scenes, hits http://gateway.vocdoni.net/rpc/

caveats: right now, the code at main and stage needs more development and still hits the old RPC endpoints for some things. in a month or two it should be complete and hit only the new APIv2

[altergui]

https://github.com/vocdoni/vocdoni-sdk follows a different branching model:

• main branch is where development PRs are merged
• there's no stage branch nor any release-* branch
• releases are tags on the main branch (starting with v0.0.1-alpha, latest is v0.0.8)
• github releases are made for each tag
  • Perfect changelog https://github.com/vocdoni/vocdoni-sdk/blob/v0.0.8/CHANGELOG.md
  • Pushed to NPM https://www.npmjs.com/package/@vocdoni/sdk/v/0.0.8

[altergui]

(following up in interop issue)