Merge branch 'main' into 2024-07-pre-push-bash-fmt-only

CONTRIBUTING.md

@@ -94,11 +94,18 @@ The SRI project follows an open contributor model, where anyone is welcome to co
 
     `cargo fmt`: this command formats your code according to the project's style guidelines. Make sure to run this command to ensure consistency in code formatting.
 
-5. **Submit a Pull Request:** once you're satisfied with your changes, submit a pull request to the original SRI repository. Provide a clear and concise description of the changes you've made. If your pull request addresses an existing issue, reference the issue number in the description. In order to contribute to the protocol implementation, every PR must be opened against `dev` branch. To better understand which is the SRI branches structure, please have a look [here](https://github.com/stratum-mining/stratum/blob/main/RELEASE.md#principal-branches).
+    Alternatively, you should consider enabling git pre-push hooks:
+    ```
+    $ git config core.hooksPath .githooks
+    ```
+
+    This will make your `git push` commands take a bit longer. But it can also save you some time with potential CI issues that could come up in your PR.
+
+5. **Submit a Pull Request:** once you're satisfied with your changes, submit a pull request to the original SRI repository. Provide a clear and concise description of the changes you've made. If your pull request addresses an existing issue, reference the issue number in the description. In order to contribute to the protocol implementation, every PR must be opened against `main` branch.
 
 6. **Review and Iterate** 
 
-7. **Merge and Close:** Once your pull request has been approved and all discussions have been resolved, a project maintainer will merge your changes into the `dev` branch. Your contribution will then be officially part of the project. The pull request will be closed, marking the completion of your contribution.
+7. **Merge and Close:** Once your pull request has been approved and all discussions have been resolved, a project maintainer will merge your changes into the `main` branch. Your contribution will then be officially part of the project. The pull request will be closed, marking the completion of your contribution.
 
 ### Your First Code Contribution
 >In order to contribute, a basic learning about git and github is needed. If you're not familiar with them, have a look at https://docs.github.com/en/get-started/start-your-journey/git-and-github-learning-resources to dig into and learn how to use them.

RELEASE.md

@@ -1,88 +1,58 @@
-# Versioning
+## Changelog
 
-SRI releases follow [SemVer 2.0.0](https://semver.org/).
+The changelog is a file that contains a curated, chronologically ordered list of
+notable changes for each version of a project. It is a way to keep track of the
+project's progress and to communicate the changes to the users and the
+community. The changelog should be updated for each release and is part of the
+release process.
 
-Given a version number `MAJOR.MINOR.PATCH`, we increment the:
-- `MAJOR` version when incompatible API changes are introduced
-- `MINOR` version when functionality is added in a backward compatible manner
-- `PATCH` version when backward compatible bug fixes are introduced
+Things to take into account while writing a changelog:
 
-SRI has a global version, which uses git tags and keeps track of how the codebase evolves across time as a whole.
+ - General release information.
+ - Breaking changes.
+ - Notable changes.
 
-Every internal SRI crate also follows SemVer 2.0.0, but each crate version is only set on the respective `Cargo.toml`,
-(no git tags), and it evolves independently of the global release version.
 
-Whenever a `PATCH` is introduced, it is applied to all the latest `MAJOR` releases.
-For example: imagine there's releases `v1.0.0`, `v1.1.0`, and `v2.0.0`. A bug is found, dating back all the way to `v1.0.0`.
-A patch is applied such that the following new tags are introduced: `v1.1.1` and `v2.0.1`.
+## Release Process
 
-# Git Branching Strategy
+Try to constrain each development cycle to a fixed time period, after which a
+release is made. After all release tasks are completed, initiate the release
+process by creating a new release branch, named `x.y.z.` referring to the
+version number, from the `main` branch.  The release branch is used as a
+breaking point and future reference for the release and should include the
+changelog entries for the release and any other release-specific tasks. Any bug
+fixes or changes for the release should be done on the release branch. When the
+release branch is ready, create a Pull Request from release branch to the `main`
+branch.  Once the Pull Request is approved and merged, create a new tag for the
+release branch and initiate any publishing tasks.
 
-We follow a simplified [gitflow](https://nvie.com/posts/a-successful-git-branching-model/) branching strategy.
+Usually the release process is as follows:
 
-Although our strategy is very similar to the classic gitflow model, we do not keep release branches.
+1. Create a new release branch from the `main` branch.
+2. Amend the changelog with the new release information.
+3. Create a Pull Request with `main` branch as base.
+4. Merge the Pull Request.
+5. Create a new tag for the release branch.
+6. Publish the release.
 
-![](git-branching.png)
 
-## Principal Branches
+## Versioning
 
-The SRI repo holds two principal branches with an infinite lifetime:
-- `main`
-- `dev`
+Protocol and Utils crates follow SemVer 2.0.0. The version number is stored in
+the `Cargo.toml` file of each crate. If a breaking change is introduced to one
+of the crates, the version number must be updated accordingly, otherwise a
+SemVer CI check would fail. Note that this does not apply to the `roles` and
+other crates in the repository.
 
-We consider `main` to be the branch where the source code of `HEAD` always reflects the latest release.
+The general SRI version does not follow any SemVer rules. You can track the
+releases on Github Releases in the repository.
 
-We consider `dev` to be the branch where the source code of `HEAD` always reflects the latest changes in the development cycle.
 
-The SRI team will decide the appropriate time when the changes to `dev` are merged back into `main` and then tagged with a release number while bumping `MAJOR`, `MINOR`, or `PATCH`.
+## Tags and Branches
 
-## Feature Branches
-
-New features are developed into separate branches that only live in the contributor's forks.
-
-- branch off from: `dev`
-- merge back into: `dev`
-- naming convention: `feat-x`, where `x` describes the feature
-
-## Patch Branches
-
-Bugs are patched into separate branches that only live in the contributor's forks.
-
-- branch off from: `dev`
-- merge back into: `dev`
-- naming convention: `patch-x`, where `x` describes the bug/patch
-
-## Release Branches
-
-Every new release, a branch is created.
-
-- branch off from: `main`
-- naming convention: `vMAJOR.MINOR.PATCH`
-
-# Releasing Roles Binaries
-
-The [release page of SRI repo](https://github.com/stratum-mining/stratum/releases) provides executable binaries for all SRI roles, targeting popular hardware architectures.
-
-The GitHub binary releases of the roles are handled in the `release-bin.yaml` workflow.
-
-This workflow is manually started by navigating to the "Actions" tab in the SRI repo, then navigating to the Release workflow section, and clicking "Run Workflow".
-
-Every time the workflow is manually triggered, the correct release branch must be chosen.
-
-Note: in order to be able to manually trigger the "Run Workflow" button, the user needs to have "Write" permissions on the repository, otherwise the button will not show up on the UI.
-
-# Publishing Library Crates
-
-Although SRI has a global release cycle, which is attached to the binaries, each internal crate also has its own versioning history.
-
-Lib crates are published to crates.io in the `release-lib.yaml` workflow. The workflow tries to update all the library crates. 
-
-If a crate is not updated successfully, the step will fail, but since all steps have `continue-on-error` set to true, the workflow will continue.
-
-Since steps can fail, the output of the action must be manually checked.
-
-Every PR to `main` needs to increase the version of whatever crate it is touching. Otherwise, we will mess up the dependency chain of whoever is fetching from crates.io
-
-Manually running `cargo release` in the various workspaces helps to prepare the version number before the releases are published.
-
-Every time we bump some crate's version, `release-libs.yaml` needs to be manually triggered in order to update crates.io.
+- Changes to `main` branch should be added through a merge commit.
+- The `main` branch is the default branch and it is always active.
+- The `main` branch is protected and requires a pull request to merge changes
+  with at least 2 approvals.
+- Each release is tagged with the version number of the release and a release
+  branch is kept for future reference or fixes.