Improve contributing workflow: transition to simplified git flow with automatic release of beta versions

.github/workflows/build.yml

@@ -5,7 +5,7 @@ on:
   workflow_dispatch:
   push:
     branches:
-      - master
+      - develop
     paths:
       - "packages/**"
       - ".github/workflows/build.yml"
@@ -198,9 +198,60 @@ jobs:
           FOLDER: .log4brains/out
           TARGET_FOLDER: adr
 
-  # release:
-  #   [...]
-  #
-  # This part is now done manually after this pipeline is successful
-  # by running `yarn release`
-  # This enables to group multiple successive merges into a single release and to better control the changelog
+  release:
+    needs: publish-pages # we could perform this step in parallel but this acts as a last end-to-end test before releasing
+    strategy:
+      # We use a matrix even if it's not needed here to be able to re-use the same Yarn setup snippet everywhere
+      matrix:
+        os: [ubuntu-latest]
+        node-version: [16.x] # Active LTS (https://github.com/nodejs/release)
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          fetch-depth: 0 # fetch all history for Lerna (https://stackoverflow.com/a/60184319/9285308)
+
+      - name: fetch all git tags for Lerna # (https://stackoverflow.com/a/60184319/9285308)
+        run: git fetch --depth=1 origin +refs/tags/*:refs/tags/* || true
+
+      # Beginning of yarn setup [KEEP IN SYNC BETWEEN ALL WORKFLOWS] (copy/paste of ci.yml's snippet)
+      - name: use node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v1
+        with:
+          node-version: ${{ matrix.node-version }}
+          registry-url: https://registry.npmjs.org/
+      - name: cache all node_modules
+        id: cache-modules
+        uses: actions/cache@v2
+        with:
+          path: "**/node_modules"
+          key: ${{ runner.os }}-v${{ matrix.node-version }}-node_modules-${{ hashFiles('yarn.lock', '**/package.json') }}
+      - name: find location of global yarn cache
+        id: yarn-cache
+        if: steps.cache-modules.outputs.cache-hit != 'true'
+        run: echo "::set-output name=dir::$(yarn cache dir)"
+      - name: cache global yarn cache
+        uses: actions/cache@v2
+        if: steps.cache-modules.outputs.cache-hit != 'true'
+        with:
+          path: ${{ steps.yarn-cache.outputs.dir }}
+          key: ${{ runner.os }}-yarn-${{ hashFiles('yarn.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-yarn-
+      - name: yarn install
+        if: steps.cache-modules.outputs.cache-hit != 'true'
+        run: yarn install --frozen-lockfile
+      # End of yarn setup
+
+      - name: build
+        run: yarn build
+
+      - name: git identity
+        run: |
+          git config --global user.name 'github-actions[bot]'
+          git config --global user.email 'github-actions[bot]@users.noreply.github.com'
+      - name: release and publish to NPM
+        run: yarn lerna publish --yes --conventional-commits --conventional-prerelease --exact --create-release github
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/ci.yml

@@ -80,8 +80,8 @@ jobs:
         with:
           fetch-depth: 0 # fetch all history to make Jest snapshot tests work
 
-      - name: fetch branch master
-        run: git fetch origin master
+      - name: fetch branch develop
+        run: git fetch origin develop
 
       # Beginning of yarn setup [KEEP IN SYNC BETWEEN ALL WORKFLOWS] (copy/paste of the snippet above)
       - name: use node.js ${{ matrix.node-version }}
@@ -114,7 +114,7 @@ jobs:
 
       - name: check for yarn.lock changes
         id: yarn-lock
-        run: git diff --quiet origin/master HEAD -- yarn.lock
+        run: git diff --quiet origin/develop HEAD -- yarn.lock
         continue-on-error: true
       #  - steps.yarn-lock.outcome == 'success' --> yarn.lock was not changed
       #  - steps.yarn-lock.outcome == 'failure' --> yarn.lock was changed
@@ -134,7 +134,7 @@ jobs:
 
       - name: test changed packages
         if: ${{ steps.yarn-lock.outcome == 'success' }}
-        run: yarn test --since origin/master
+        run: yarn test --since origin/develop
 
       - name: test all packages
         if: ${{ steps.yarn-lock.outcome == 'failure' }}

CONTRIBUTING.md

@@ -2,13 +2,7 @@
 
 :+1::tada: First of all, thanks for taking the time to contribute! :tada::+1:
 
-All your contributions are very welcome, whether it's:
-
-- Reporting a bug
-- Discussing the current state of the code
-- Submitting a fix
-- Proposing new features
-- Becoming a maintainer
+All your contributions are very welcome, whether it’s a bug fix, new feature, or enhancement. Please follow the guidelines below to ensure a smooth contribution process.
 
 Thank you so much! :clap:
 
@@ -47,17 +41,102 @@ log4brains init
 
 When you are done, run `yarn unlink-cli && npm install -g log4brains` to use the official version again.
 
-## Checks to run before pushing
+## Coding standards
+
+Ensure that your code follows our style guidelines and is fully tested. We use ESLint for code linting, and Prettier for code formatting.
+See the section below for more details about the commands to run.
+
+## Versioning and Commit Messages
+
+We use Lerna with [Semantic Versioning](https://semver.org/). Version bumps are determined automatically by commit messages using the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) format:
+
+- `fix:` for patches
+- `feat:` for new features
+- `BREAKING CHANGE:` in the footer of the message for major changes
+
+Example commit message:
 
-```bash
-yarn lint         # enforced automatically before every commit with husky+lint-staged
-yarn format:fix   # enforced automatically before every commit with husky+lint-staged
-yarn typescript   # enforced automatically before every commit with husky
-yarn test:changed # (or `yarn test` to run all the tests)
 ```
+feat: add a new command to generate specific ADRs
+```
+
+## Git workflow
+
+Log4brains follows a **simplified Git Flow** model. Here’s how the process works:
+
+1. **Fork the Repository**: First, fork the repository and clone it locally.
+2. **Create a Feature Branch**: Create a new branch for your feature or bug fix based on the `develop` branch:
+   ```bash
+   git checkout develop
+   git checkout -b my-new-feature
+   ```
+3. **Develop and Test**: Make your changes (do not forget the tests!), and ensure the following commands pass before submitting your PR:
+
+   ```bash
+   yarn lint         # enforced automatically before every commit with husky+lint-staged
+   yarn format:fix   # enforced automatically before every commit with husky+lint-staged
+   yarn typescript   # enforced automatically before every commit with husky
+   yarn test:changed # (or `yarn test` to run all the tests)
+   ```
+
+   If applicable, a pull request without tests will be rejected.
+
+4. **Rebasing**: Before creating your Pull Request, ensure it is rebased onto the latest develop to ensure that your changes can be merged without conflicts.
+
+5. **Submit a Pull Request**: When your changes are ready, push your branch to your fork and open a Pull Request (PR) to the `develop` branch of the main repository.
+
+   The PR will automatically trigger tests using GitHub Actions. If all tests pass, you can wait for a maintainer to review your PR.
+
+6. **Review Process**: A maintainer will review your PR and provide feedback. If approved, your changes will be merged into `develop` (using "Squash and Merge" to maintain a clean history).
 
-Please do not forget to add tests to your contribution if this is applicable!
+   It will then trigger automatically a **beta release** to npm, allowing users to install and test the latest changes:
+
+   ```bash
+   npm install log4brains@beta
+   ```
+
+   This helps us get feedback from early adopters before merging changes into `stable`, and thus triggering a stable release.
+
+7. **Releasing to Stable**: Once the `develop` branch is stable and tested, the maintainers will merge it into `stable`, and run manually `scripts/release.sh` to publish a new stable release to npm (TODO: should be automated in the future).
+
+### Urgent hotfix specific case
+
+In the rare case that an urgent hotfix is needed on the current stable version while not wanting to release the `develop` branch yet, you can follow this process:
+
+1. Create a new branch from `stable` (instead of `develop`)
+2. Develop and test
+3. Submit a Pull Request to `stable` (instead of `develop`)
+4. A maintainer will review, merge and release the patch
+5. Then the maintainer will merge `stable` into `develop` to ensure the hotfix is ported to the beta version
 
 ## License
 
 By contributing to Log4brains, you agree that your contributions will be licensed under its Apache 2.0 License.
+
+## Would like to become a co-maintainer?
+
+As discussed in [discussion #108](https://github.com/thomvaill/log4brains/discussions/108), I (@thomvaill), as the project's sole maintainer, struggle to dedicate enough time to ensure its stability and growth, which is critical for its continued development. To ensure the project's long-term success, it is essential to have multiple maintainers. Therefore, I am actively seeking reliable and committed co-maintainers to share the responsibilities and contribute to the project's future.
+
+To make it easier I introduce two co-maintainer roles:
+
+- **Canary Maintainers**: in charge of triaging issues, reviewing PRs, and can merge them into `develop` (and thus trigger a beta release)
+- **Core Maintainers**: in charge of the project's overall direction and vision, of releasing stable versions, and can merge `develop` into `stable` (and thus trigger a stable release)
+
+If you're interested in becoming a co-maintainer, you can start your "Mentorship Phase" by participating in code reviews and helping triage issues. This will help us assess your familiarity with the project and the workflow.
+
+**Steps to becoming a co-maintainer**:
+
+1. **Review Open PRs**: Begin by reviewing existing PRs and providing meaningful feedback. A current maintainer will mentor you through the review process.
+2. **Help Triaging Issues**: Engage with users by helping resolve issues and providing guidance.
+3. **Contribution Consistency**: Regular and meaningful contributions over time will demonstrate your knowledge and commitment.
+4. **Reach Out** to <[email protected]> to exress your interest in becomming a co-maintainer.
+
+Once we identify a trusted contributor, we will elevate them to the **Canary Maintainer** status, with permissions to merge PRs and perform other tasks.
+Later, a **Canary Maintainer** can become a **Core Maintainer** if they demonstrate a strong understanding of the project and its direction and if they are motived to take on the additional responsibilities.
+
+## Issues triage
+
+_Work in Progress_
+
+- **Core Maintainers** are responsible for managing the [milestones](https://github.com/thomvaill/log4brains/milestones) of the project: this enables contributor to see what is planned for the next release, and what is the priority of the issues
+- **Canary Maintainers** are responsible for triaging issues and PRs

README.md

@@ -2,12 +2,12 @@
 
 <p align="center">
   <a href="#readme">
-    <img src="https://github.com/thomvaill/log4brains/raw/master/docs/Log4brains-logo-full.png" alt="Log4brains logo" width="276" />
+    <img src="https://github.com/thomvaill/log4brains/raw/develop/docs/Log4brains-logo-full.png" alt="Log4brains logo" width="276" />
   </a>
 </p>
 
 <p align="center">
-  <a href="https://github.com/thomvaill/log4brains/blob/master/LICENSE">
+  <a href="https://github.com/thomvaill/log4brains/blob/develop/LICENSE">
     <img src="https://img.shields.io/badge/license-Apache%202-blue" alt="License" />
   </a>
   <a href="https://github.com/thomvaill/log4brains/actions?query=workflow%3ABuild">
@@ -64,7 +64,7 @@ By logging your decisions chronologically, you will be able to:
 <br />
 <p align="center">
   <a href="https://www.youtube.com/watch?v=HDEwOCn9T0w" title="Click to watch the full screencast">
-    <img src="https://github.com/thomvaill/log4brains/raw/master/docs/demo.gif" alt="Log4brains demo" width="838" />
+    <img src="https://github.com/thomvaill/log4brains/raw/develop/docs/demo.gif" alt="Log4brains demo" width="838" />
   </a>
 </p>
 <p align="center"><a href="https://www.youtube.com/watch?v=HDEwOCn9T0w">🎞️ Watch the full screencast</a> - <a href="https://thomvaill.github.io/log4brains/adr/">⚡ See an example (Log4brains' own ADRs)</a></p>
@@ -93,7 +93,7 @@ in the same git repository, to keep them in sync.
 To get started, run these commands inside your project root folder:
 
 ```bash
-npm install -g log4brains
+npm install -g log4brains # if you want to install the latest beta version, run `npm install -g log4brains@beta` instead
 log4brains init
 ```
 
@@ -163,7 +163,7 @@ name: Publish Log4brains
 on:
   push:
     branches:
-      - master
+      - main
 jobs:
   build-and-publish:
     runs-on: ubuntu-latest
@@ -208,7 +208,7 @@ Finally, you can [enable your GitHub page](https://docs.github.com/en/free-pro-t
 - Then, select the `/ (root)` folder
 
 You should now be able to see your knowledge base at `https://<username>.github.io/<repository>/log4brains/`.
-It will be re-built and published every time you push on `master`.
+It will be re-built and published every time you push on `main`.
 
 </p>
 </details>
@@ -237,7 +237,7 @@ pages:
 ```
 
 You should now be able to see your knowledge base at `https://<username>.gitlab.io/<repository>/log4brains/`.
-It will be re-built and published every time you push on `master`.
+It will be re-built and published every time you push on `main`.
 
 </p>
 </details>

docs/adr/20240926-transition-to-simplified-git-flow.md

@@ -0,0 +1,60 @@
+# Transition to Simplified Git Flow
+
+- Status: draft
+- Date: 2024-09-26
+
+## Context and Problem Statement
+
+The existing GitHub Flow process lacked clarity for stable releases and was overly manual, making it hard to delegate and streamline contributions. The need was for a more structured yet simple workflow that would facilitate testing and contributions while automating releases.
+
+Additional context in [Discussion #108: Does this project need a new maintainer?](https://github.com/thomvaill/log4brains/discussions/108)
+
+## Decision Drivers
+
+- Need for automation in releases.
+- Be able to merge more quickly whithout breaking the stable branch, while making it possible for beta testers to test the new features.
+- Easier delegation to new maintainers.
+- Simplified yet structured process for contributors.
+- Clearer separation between ongoing development and stable releases.
+
+## Considered Options
+
+- Continue with GitHub Flow.
+- Transition to Simplified Git Flow.
+- Full Git Flow with release branches.
+
+## Decision Outcome
+
+Chosen option: **Simplified Git Flow**, because it provides structure (separating development from stable releases) without excessive complexity. It also allows for automated canary/beta releases and easier delegation for merging feature branches to `develop`.
+
+### Positive Consequences
+
+- Clear separation of development (`develop`) and stable (`stable`) branches.
+- Automated beta releases from `develop` to facilitate early testing.
+- Allows contributors to participate in testing beta features and reduces the manual overhead of testing and releasing stable versions
+- Easier to delegate responsibilities (Canary vs. Core Maintainers, see [CONTRIBUTING.md](CONTRIBUTING.md)).
+- More streamlined versioning via Conventional Commits.
+
+### Negative Consequences
+
+- Contributors need to adjust to using `develop` for PRs instead of `stable`.
+- Slight learning curve for Conventional Commits.
+
+## Pros and Cons of the Options
+
+### Continue with GitHub Flow
+
+- Good, because it’s simpler with fewer branches.
+- Bad, because it lacks separation of development and stable code.
+- Bad, because manual testing and release increase bottlenecks.
+
+### Simplified Git Flow
+
+- Good, because it balances structure with simplicity.
+- Good, because it allows easier delegation to maintainers.
+- Bad, because it introduces a new `develop` branch, which may need adjustment for contributors.
+
+### Full Git Flow
+
+- Good, because it provides a full release management process.
+- Bad, because it adds unnecessary complexity for smaller open-source projects.

docs/adr/README.md

@@ -30,6 +30,6 @@ log4brains adr new
 
 ## More information
 
-- [Log4brains documentation](https://github.com/thomvaill/log4brains/tree/master#readme)
-- [What is an ADR and why should you use them](https://github.com/thomvaill/log4brains/tree/master#-what-is-an-adr-and-why-should-you-use-them)
+- [Log4brains documentation](https://github.com/thomvaill/log4brains/tree/develop#readme)
+- [What is an ADR and why should you use them](https://github.com/thomvaill/log4brains/tree/develop#-what-is-an-adr-and-why-should-you-use-them)
 - [ADR GitHub organization](https://adr.github.io/)

docs/adr/index.md

@@ -19,7 +19,7 @@ Moreover, maintaining this documentation aims at:
 
 ## Usage
 
-This website is automatically updated after a change on the `master` branch of the project's Git repository.
+This website is automatically updated after a change on the `develop` branch of the project's Git repository, from the latest beta version of Log4brains.
 In fact, the developers manage this documentation directly with markdown files located next to their code, so it is more convenient for them to keep it up-to-date.
 You can browse the ADRs by using the left menu or the search bar.
 
@@ -31,6 +31,6 @@ The decision process is entirely collaborative and backed by pull requests.
 
 ## More information
 
-- [Log4brains documentation](https://github.com/thomvaill/log4brains/tree/master#readme)
-- [What is an ADR and why should you use them](https://github.com/thomvaill/log4brains/tree/master#-what-is-an-adr-and-why-should-you-use-them)
+- [Log4brains documentation](https://github.com/thomvaill/log4brains/tree/develop#readme)
+- [What is an ADR and why should you use them](https://github.com/thomvaill/log4brains/tree/develop#-what-is-an-adr-and-why-should-you-use-them)
 - [ADR GitHub organization](https://adr.github.io/)

lerna.json

@@ -8,7 +8,7 @@
   "command": {
     "version": {
       "message": "chore(release): publish %s",
-      "allowBranch": "master"
+      "allowBranch": "develop"
     }
   }
 }

packages/cli-common/README.md

@@ -11,7 +11,7 @@ npm install -g log4brains
 
 ## Documentation
 
-- [Log4brains README](https://github.com/thomvaill/log4brains/blob/master/README.md)
+- [Log4brains README](https://github.com/thomvaill/log4brains/blob/develop/README.md)
 
 ## Development