diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index fffd45c1..adf2785a 100644 --- a/.github/workflows/build.yml +++ b/.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 }} diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 99b8c193..9da5cb2c 100644 --- a/.github/workflows/ci.yml +++ b/.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' }} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 102b2ce7..facb11af 100644 --- a/CONTRIBUTING.md +++ b/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 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 diff --git a/README.md b/README.md index 883d84cb..00bacf0e 100644 --- a/README.md +++ b/README.md @@ -2,12 +2,12 @@

- Log4brains logo + Log4brains logo

- + License @@ -64,7 +64,7 @@ By logging your decisions chronologically, you will be able to:

- Log4brains demo + Log4brains demo

🎞️ Watch the full screencast - ⚡ See an example (Log4brains' own ADRs)

@@ -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://.github.io//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`.

@@ -237,7 +237,7 @@ pages: ``` You should now be able to see your knowledge base at `https://.gitlab.io//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`.

diff --git a/docs/adr/20240926-transition-to-simplified-git-flow.md b/docs/adr/20240926-transition-to-simplified-git-flow.md new file mode 100644 index 00000000..164b3acf --- /dev/null +++ b/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. diff --git a/docs/adr/README.md b/docs/adr/README.md index 5cd26c01..cc0e031b 100644 --- a/docs/adr/README.md +++ b/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/) diff --git a/docs/adr/index.md b/docs/adr/index.md index bedb18bd..39909a78 100644 --- a/docs/adr/index.md +++ b/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/) diff --git a/lerna.json b/lerna.json index 48435ce3..cc0bc6d2 100644 --- a/lerna.json +++ b/lerna.json @@ -8,7 +8,7 @@ "command": { "version": { "message": "chore(release): publish %s", - "allowBranch": "master" + "allowBranch": "develop" } } } diff --git a/packages/cli-common/README.md b/packages/cli-common/README.md index 457b78dd..9917dcc7 100644 --- a/packages/cli-common/README.md +++ b/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 diff --git a/packages/cli/README.md b/packages/cli/README.md index 9e7e0b70..15e1000a 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -11,4 +11,4 @@ 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) diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.ts index 9b7269f6..bc6357aa 100644 --- a/packages/cli/src/cli.ts +++ b/packages/cli/src/cli.ts @@ -17,7 +17,7 @@ import { } from "./commands"; const templateExampleUrl = - "https://raw.githubusercontent.com/thomvaill/log4brains/master/packages/init/assets/template.md"; + "https://raw.githubusercontent.com/thomvaill/log4brains/stable/packages/init/assets/template.md"; function findRootFolder(cwd: string): string { if (fs.existsSync(path.join(cwd, ".log4brains.yml"))) { diff --git a/packages/core/README.md b/packages/core/README.md index 34cf0b15..fcabb01f 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -39,4 +39,4 @@ const l4b = Log4brains.create(process.cwd()); ## Documentation - TypeDoc documentation (TODO) -- [Log4brains README](https://github.com/thomvaill/log4brains/blob/master/README.md) +- [Log4brains README](https://github.com/thomvaill/log4brains/blob/develop/README.md) diff --git a/packages/core/src/infrastructure/api/transformers/adr-transformers.ts b/packages/core/src/infrastructure/api/transformers/adr-transformers.ts index ae26b390..83ab4c94 100644 --- a/packages/core/src/infrastructure/api/transformers/adr-transformers.ts +++ b/packages/core/src/infrastructure/api/transformers/adr-transformers.ts @@ -11,7 +11,7 @@ function buildViewUrl( return undefined; } const uri = repositoryConfig.viewFileUriPattern - .replace("%branch", "master") // TODO: make this customizable + .replace("%branch", "master") // TODO: make this customizable, and fix the branch name for the Log4brains repository (develop instead of master) .replace("%path", file.path.pathRelativeToCwd); return `${repositoryConfig.url.replace(/\.git$/, "")}${uri}`; } diff --git a/packages/init/README.md b/packages/init/README.md index bb2d73ef..980646c3 100644 --- a/packages/init/README.md +++ b/packages/init/README.md @@ -11,4 +11,4 @@ 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) diff --git a/packages/init/assets/README.md b/packages/init/assets/README.md index 74bccd30..50a9506b 100644 --- a/packages/init/assets/README.md +++ b/packages/init/assets/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/) diff --git a/packages/init/assets/index.md b/packages/init/assets/index.md index 7b5e225f..2ccc9acb 100644 --- a/packages/init/assets/index.md +++ b/packages/init/assets/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 `main` branch of the project's Git repository. 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/) diff --git a/packages/web/README.md b/packages/web/README.md index a3c1a806..abc579c1 100644 --- a/packages/web/README.md +++ b/packages/web/README.md @@ -11,4 +11,4 @@ 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) diff --git a/scripts/release.sh b/scripts/release.sh index 1d2d6e0d..cc8ad71f 100755 --- a/scripts/release.sh +++ b/scripts/release.sh @@ -17,9 +17,9 @@ npm config set registry https://registry.npmjs.org/ cd "${ROOT_PATH}" -if [[ "$(git rev-parse --abbrev-ref HEAD)" != "master" ]] +if [[ "$(git rev-parse --abbrev-ref HEAD)" != "stable" ]] then - echo "Please run this command from the master branch" + echo "Please run this command from the stable branch" exit 1 fi