{"id":20438427,"url":"https://github.com/tinymce/beehive-flow","last_synced_at":"2025-04-12T22:35:40.160Z","repository":{"id":38213325,"uuid":"294303785","full_name":"tinymce/beehive-flow","owner":"tinymce","description":"A git branching process and CLI tool.","archived":false,"fork":false,"pushed_at":"2025-01-23T01:13:38.000Z","size":1253,"stargazers_count":1,"open_issues_count":0,"forks_count":4,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-03-26T16:39:09.019Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tinymce.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-09-10T04:35:49.000Z","updated_at":"2025-01-23T01:13:40.000Z","dependencies_parsed_at":"2024-10-24T04:39:58.167Z","dependency_job_id":"5d3a32c8-87e2-4e03-949a-63802ad70899","html_url":"https://github.com/tinymce/beehive-flow","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tinymce%2Fbeehive-flow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tinymce%2Fbeehive-flow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tinymce%2Fbeehive-flow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tinymce%2Fbeehive-flow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tinymce","download_url":"https://codeload.github.com/tinymce/beehive-flow/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248642488,"owners_count":21138351,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-15T09:11:00.390Z","updated_at":"2025-04-12T22:35:40.132Z","avatar_url":"https://github.com/tinymce.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# beehive-flow\n\nBeehive Flow is a git branching process and a supporting CLI tool. It is designed for packaged software and libraries, \nparticularly those with many past versions requiring active support. Beehive Flow is prescriptive about what the project's\nversion numbers are and how they change through the branching process. CI is explicitly considered in the process, \nwith a set of commands to be run at different stages of the build. \n\nBeehive Flow is designed to support publishing prerelease versions of each build of each branch. It does this by timestamping\nversion numbers at the start of a build. \n\nBeehive Flow is similar to [GitLab flow with release versions](https://docs.gitlab.com/ee/topics/gitlab_flow.html#release-branches-with-gitlab-flow),\nand is compatible with Semantic Versioning. It also takes inspiration from [git-flow](https://nvie.com/posts/a-successful-git-branching-model/). \n\nThis readme is the canonical definition of the branching process. This git repo implements the branch process for NPM projects. \nSupport for monorepos using yarn workspaces is planned.\n\n## Process Overview\n\nbeehive-flow uses the following branch names, each forming part of the process:\n\n - main\n - release/x.y\n - feature/FEATURE_CODE\n - hotfix/FEATURE_CODE\n - spike/FEATURE_CODE\n\nBranch names and versions are strict and enforced.\n\nAll new work happens in `feature/*` branches which are merged to the `main` branch:\n\n```\n                       feature/BLAH-123\n  main                 +-----------\n (x.y.0-rc)            |           \\\n  +--------------------+------------+-----\n```\n\nThe `main` branch can be branched to `release/x.y` branches to maintain older minor versions. These branches are created from old releases with `behive-flow revive`:\n\n```\n  main\n (1.2.3)                    (2.1.5-rc)\n  +- - - - - - - - - - - - - +--------------\n  |\n  ↓             [revive 1.2]:\n  - - - - - - - - - - - - - - +-------------\n                              release/1.2\n                             (1.2.4-rc)\n```\n\nFor advanced use-cases, a `release/x.y` branch can be created before `x.y.0` is released, using `beehive-flow prepare`:\n\n```\n  main                 \n (1.2.0-rc)           (1.3.0-rc)\n  +-----------------+--------------------                             \n         [prepare]: |                             \n                    +--------------------\n                    release/1.2                  \n                    (1.2.0-rc)        \n```\n\nTo make changes to a `release/x.y` branch, create a `hotfix/*` branch, cherry-pick from `main`, then merge:\n\n```\n  main\n (1.2.0-rc)\n  +---------+---------------------------------\n            |              | |  cherry-pick and tweak\n            |              ↓ ↓\n            |            +---------+  hotfix/BLAH-123\n            |            |          \\\n            +------------+-----------+--------\n            release/1.3\n            (1.2.0-rc)\n```\n\nBeehive Flow is designed so that every commit can be published. To avoid conflicts with stable releases, the version in\nthe `package.json` will almost always be a \"release candidate\" version like `x.y.z-rc`. A stable release takes place in\ntwo stages: `beehive-flow release` and `beehive-flow advance-ci`. The two-stage process is shown below:\n\n```\n main\n(1.2.4-rc)           (1.2.4)              (1.2.5-rc)\n-+--------------------+--------------------+------------\n            [release]:        [advance-ci]:\n```\n\nTo perform a release, run either `beehive-flow release main` or `beehive-flow release x.y`, depending on whether you\nwant to release from the `main` branch or a `release/x.y` branch. This will \"stabilise\" the version number on that\nbranch, removing the `-rc`. From there, CI will publish your release and then run `beehive-flow advance-ci` to update\nthat branch to the next release candidate version.\n\nTo avoid duplicate version numbers, `beehive-flow stamp` is run at the start of any CI build for a release candidate,\nwhich adds some metadata to the version string, such as the timestamp of the build, and the git SHA of the commit.\n\n## Preparing for release\n\nTo release a stable version (such as `a.b.x`) with Beehive Flow, you need to set the version of the branch you plan to\nrelease from to `a.b.x-rc`. The branch you release from should either be `main`, or `release/a.b`, which one you choose\nis based on the following questions:\n\n1. Does the branch `release/a.b` exist?\n\nIf the branch `release/a.b` exists, then all releases of the form `a.b.*` should take place from that branch. The\nversion set in this branch will already be `a.b.x-rc`, so no manual editing of the version is necessary.\n\n2. Have you upgraded the `main` branch version above `a.b.*`?\n\nIf no `release/a.b` branch exists, but the version on main is already greater than `a.b.*`, you will need to create a\n`release/a.b` branch. Run `beehive-flow revive a.b` to create this branch, which will have its version automatically\nset to `a.b.x-rc`. Prepare your release on this branch.\n\n3. Do you need a stabilisation period before your release?\n\nIf no `release/a.b` branch exists, and the version on `main` is `a.b.x-rc`, you have two options for releasing. The\n**simple** variant is to release directly from `main`, with the command `beehive-flow release main`. However, if you\nneed to do work to stabilise this release (and want to do work on your next minor release with the `main` branch in\nparallel with this) then you'll need the **advanced** variant. In this case, run `beehive-flow prepare`, which will\nbump the version of the `main` branch to the next minor (`a.c.0-rc`) and create a `release/a.b` branch with version\n`a.b.x-rc`.\n\n## Minor and Major Upgrades\n\nWith the exception of `prepare`, which is for advanced use-cases only, the Beehive Flow tool will not perform minor or\nmajor version upgrades to any branch. You must manually upgrade the version in your package.json, which is allowed on\nany branch except a `release/x.y` branch. Be sure to keep the `-rc` at the end of your version number: changing\n`1.2.3-rc` to `1.3.0-rc` or `2.0.0-rc` is fine, but changing `1.2.3-rc` to `1.3.0` is not.\n\nWhile Beehive Flow does not specify how to do these upgrades, we recommend upgrading the version number in the\n`feature/*` branch that introduces the first change that would require the upgrade. For example:\n\n```\n              feature/*\n             (1.2.3-rc)     (1.3.0-rc)\n main         +--------------+--------+\n(1.2.3-rc)    |                        \\\n +------------+-------------------------+----------\n                                       (1.3.0-rc)\n```\n\n## Feature vs Spike branches\n\nFeature branches are branched off `main` and are named `feature/*`. Most new work is done here. It doesn't matter if it's a feature, improvement, task, \nrefactor, bugfix or any other type of change... except for spikes.\n\nSpike branches are branched off `main` and are named `spike/*`. These are treated similarly to feature branches, but are just intended to indicate that\nthe work is experimental and not to be merged.\n\n## About rc and prerelease versions\n\nThe only allowed prerelease version is \"rc\". \n\n`main` and `release/x.y` alternate between rc and release versions. Any other prerelease version will error.\n\nOther branches should always have \"rc\" versions, though this is not enforced.\n\nWhen stamping, different prerelease versions are chosen based on the branch type (see below).\n\n## Commands\n\nNote: the `stamp`, `advance-ci` and `publish` commands operate on a checkout in the current working directory,\nwhereas the other commands make a fresh clone in a temp directory.\n\nFor a detailed description about command-line usage and arguments, run `yarn beehive-flow --help` or `yarn beehive-flow --help COMMAND`.\n\n### release main\n\nThis signifies that branch `main` is ready for release. \n\nVersion changes:\n\n - `main`: `a.b.c-rc` -\u003e `a.b.c`\n\n### release a.b\n\nThis signifies that branch `release/a.b` is ready for release. \n\nVersion changes:\n\n - `release/a.b`: `a.b.c-rc` -\u003e `a.b.c`\n\n### advance a.b\n\nThis signifies that branch `release/a.b` has been released and is ready to accept changes for the next patch release. \nThis command is intended to be run manually. Usually, `advance-ci` should be used instead.\n\nVersion changes:\n\n - `release/a.b`: `a.b.c` -\u003e `a.b.d-rc`\n\n### advance-ci\n\nThis command is similar to `advance`, however:\n\n - it works in a current directory\n - if the current directory is not a release branch in release ready state, it exits successfully, whereas `advance` errors\n - it doesn't have the `git-url` or version parameters\n\n### stamp\n\nThis command should be run at the start of a build. This command does the following:\n\n 1. Checks that the package.json file has a valid version for the branch.\n 2. Changes the version to a \"timestamped\" version, so that each build can be published (except for release versions).\n \nThe timestamping changes the package.json file. The idea is to build and publish, but not to commit the changes.\n\nVersions are changed thus:\n\n - On a feature branch, `a.b.0-*` becomes `a.b.0-feature.TIMESTAMP.sha-GITSHA`\n - On a hotfix branch, `a.b.c-*` becomes `a.b.c-hotfix.TIMESTAMP.sha-GITSHA`\n - On a spike branch, `a.b.c-*` becomes `a.b.c-spike.TIMESTAMP.sha-GITSHA`\n - On a main or release branch in rc state, `a.b.c-rc` becomes `a.b.c-rc.TIMESTAMP.sha-GITSHA`\n - On a main or release branch in release state, no changes are made.\n \nTimestamp format is `yyyyMMddHHmmssSSS` in UTC. The short git sha format is used.\n\nNote: this command operates on the checkout in the current working directory.\n\n### revive a.b\n\nThis command allows a `release/a.b` branch to be created from previous release tags. This is useful if a hotfix needs to be backported to an older version. This command does the following:\n\n1. Finds all tags that match the specified `a.b` version.\n2. Sorts the tags and determines the most recent patch release.\n3. Creates the new `release/a.b` branch from the tag.\n4. Advances the version to the next RC patch release.\n\nVersion changes:\n\n- `release/a.b`: `a.b.c` -\u003e `a.b.d-rc`\n\n### prepare\n\nThis signifies that `main` is ready for stabilization.\n`main` is branched as `release/a.b`, where `a.b` come from package.json\n\nVersion changes\n\n- `main`: `a.b.x-rc` -\u003e `a.c.0-rc`\n- `release/a.b`: `a.b.x-rc`\n\n### publish\n\nThis command does an `npm publish` and sets npm tags based on the repository state.\n\n - feature/hotfix/spike branches are tagged with their branch name\n - main and release branches in rc state are tagged `rc-a.b`\n - main and release branches in release state are tagged `release-a.b`. \n - main and release branches in rc or release state are also tagged `latest` if this is the release with the highest version number.\n\n`beehive-flow publish` also git tags any release builds as `packagename@version`. \n\n#### Determining the `latest` build\n\nWhen publishing, `beehive-flow` reads the existing NPM tags from the repo and uses those to determine whether or not\nto set `latest` on the new build. `latest` is set if the new build's number is \"greater\" than the existing build. \n\nNote that all release builds are considered greater than all rc builds. So, for a new project, you may have a period\nwhere your `latest` tag only points to `rc` builds, but after your first release, `latest` will always point to a release build.\n\nNote that the first publish of a build is always tagged `latest`.\n\n### status\n\nThis command prints out beehive-flow's interpretation the current status of the repo, in JSON format.\nThis is useful for integrating with other CI tools.\n\nRun this as `yarn run --silent beehive-flow status` otherwise yarn's output will make stdout invalid JSON.\n\nExample:\n\n```\n$ yarn --silent beehive-flow status\n{\n  \"currentBranch\": \"feature/TINY-6867\",\n  \"version\": {\n    \"major\": 0,\n    \"minor\": 11,\n    \"patch\": 0,\n    \"preRelease\": \"rc\"\n  },\n  \"versionString\": \"0.11.0-rc\",\n  \"branchType\": \"feature\",\n  \"branchState\": \"feature\",\n  \"isLatest\": false\n}\n```\n\nNote: this command will fail if the repo is in an invalid state.\n\nFields:\n\n - currentBranch - the current git branch\n - version - parsed version in `package.json`. Has `major`, `minor` and `patch` fields and may have `preRelease` and `buildMetadata` fields if present.\n - versionString - raw version string\n - branchType - one of: `main`, `feature`, `hotfix`, `spike`, `release`\n - branchState - state of the branch - similar to branchType, but splits release branches into 2 separate states. \n   May be one of: `main`, `feature`, `hotfix`, `spike`, `releaseCandidate`, `releaseReady`\n - isLatest - If this version were to be published, would it be the `latest` build?\n\nIf you want to read this from a Jenkinsfile:\n\n```\ndef shJson(String script) {\n    def s = sh(script: script, returnStdout: true);\n    return readJSON(text: s);\n}\n\ndef beehiveFlowStatus = shJson(\"yarn run --silent beehive-flow status\");\n```\n\nThen, if you want to run something when beehive-flow would publish a new release build of the latest release:\n\n```\nif (beehiveFlowStatus.branchState == 'releaseReady' \u0026\u0026 beehiveFlowStatus.isLatest) {\n\n}\n```\n\n## CI Instructions\n\nCI needs to check out a real branch, not just a detached head.\n\nAt the start of the build, run `stamp`. If the build is successful, run `advance-ci`.\n\n## Adding beehive-flow to my project\n\nThese instructions assume Jenkins, yarn, TypeScript, mocha and eslint. \n\n 1. Best to disable CI during the changeover.\n 2. Ensure you have a \"main\" branch - e.g. change your \"master\" branch to \"main\"\n 3. `yarn add -D @tinymce/beehive-flow`\n 4. Change your `Jenkinsfile` to something like below. Note there are issues running `beehive-flow publish` from `yarn` (see FAQ below).\n    ```\n    node(\"primary\") {\n      stage (\"checkout\") {\n        checkout scm\n      }\n    \n      stage(\"dependencies\") {\n        sh \"yarn install\"\n      }\n    \n      stage(\"stamp\") {\n        sh \"yarn beehive-flow stamp\"\n      }\n    \n      stage(\"build\") {\n        sh \"yarn build\"\n      }\n    \n      stage(\"lint\") {\n        sh \"yarn lint\"\n      }\n    \n      stage(\"test\") {\n        sh \"yarn test\"\n      }\n    \n      stage(\"publish\") {\n        sshagent(credentials: ['my-git-credentials']) {\n          sh \"yarn beehive-flow publish\"        \n          sh \"yarn beehive-flow advance-ci\"\n        }\n      }\n    }\n    ```\n 5. Note the yarn commands. Set up scripts in `package.json` to this effect. e.g.\n    ```\n    \"build\": \"tsc\",\n    \"lint\": \"eslint src/**/*.ts\",\n    \"test\": \"yarn mocha\"\n    ```\n\n## FAQ\n\n### Does beehive-flow work with yarn workspaces, lerna or monorepos?\n\nNot yet, but this is planned.\n\n### Does beehive-flow work with any types of package other than NPM?\n\nNot at this stage.\n\n### Are there issues running `beehive-flow publish` from yarn?\n\n`beehive-flow publish` uses `npm publish` to publish. When running this via yarn, yarn sets the environment variable\n`npm_config_registry` to `https://registry.yarnpkg.com`. Depending on your CI config, this may cause you to get errors like this:\n\n```\nnpm ERR! 404 Not Found - PUT https://registry.yarnpkg.com/@tinymce%2fbeehive-flow - Not found\n``` \n\nTo work around this, there are several options:\n1. Run `yarn config set registry https://registry.npmjs.org/ -g` on your CI nodes (sets the registry in `~/.yarnrc`)\n2. Run `yarn config set registry https://registry.npmjs.org/` in each project (sets the registry in the project's `.yarnrc`)\n3. Set the publishConfig in your package.json file.\n4. Instead of running from yarn, run `npx --no-install beehive-flow publish`. The `--no-install` forces npx to use your project's\n   pinned beehive-flow and if it's not there, it fails instead of downloading the latest beehive-flow.\n\nAt Tiny, we're using option 1.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftinymce%2Fbeehive-flow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftinymce%2Fbeehive-flow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftinymce%2Fbeehive-flow/lists"}