Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 2 commits into from
Oct 28, 2024
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fa7691f
chore: transition to simplified git flow with automatic release of be…
thomvaill Sep 26, 2024
2a58b7f
docs: create issues triage part
thomvaill Oct 4, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 58 additions & 7 deletions .github/workflows/build.yml
View file
Open in desktop
thomvaill marked this conversation as resolved.
Show resolved Hide resolved
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ on:
workflow_dispatch:
push:
branches:
- master
- develop
paths:
- "packages/**"
- ".github/workflows/build.yml"
Expand Down Expand Up @@ -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 }}
8 changes: 4 additions & 4 deletions .github/workflows/ci.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 }}
Expand Down Expand Up @@ -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
Expand All @@ -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' }}
Expand Down
107 changes: 93 additions & 14 deletions CONTRIBUTING.md
View file
Open in desktop
thomvaill marked this conversation as resolved.
Show resolved Hide resolved
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down Expand Up @@ -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 <thomvaill@bluebricks.dev> 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
14 changes: 7 additions & 7 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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">
Expand Down Expand Up @@ -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>
Expand Down Expand Up @@ -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
```

Expand Down Expand Up @@ -163,7 +163,7 @@ name: Publish Log4brains
on:
push:
branches:
- master
- main
jobs:
build-and-publish:
runs-on: ubuntu-latest
Expand Down Expand Up @@ -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>
Expand Down Expand Up @@ -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>
Expand Down
60 changes: 60 additions & 0 deletions docs/adr/20240926-transition-to-simplified-git-flow.md
View file
Open in desktop
thomvaill marked this conversation as resolved.
Show resolved Hide resolved
Original file line number Diff line number Diff line change
@@ -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.
4 changes: 2 additions & 2 deletions docs/adr/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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/)
6 changes: 3 additions & 3 deletions docs/adr/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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/)
2 changes: 1 addition & 1 deletion lerna.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
"command": {
"version": {
"message": "chore(release): publish %s",
"allowBranch": "master"
"allowBranch": "develop"
}
}
}
2 changes: 1 addition & 1 deletion packages/cli-common/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
Loading
Loading