From cbecffb7bfe3f0f159eb10a46493e22af91ecf50 Mon Sep 17 00:00:00 2001 From: David Edey Date: Mon, 13 Jan 2025 16:06:24 +0000 Subject: [PATCH] docs: Update docs to make `develop` the default branch --- .github/CODEOWNERS | 17 ++++++++ .github/pull_request_template.md | 23 +++++++---- CHANGELOG.md | 71 ++++++++++++++++++++++++++++++++ README.md | 6 +++ docs/branching-strategy.md | 19 ++++----- 5 files changed, 116 insertions(+), 20 deletions(-) create mode 100644 .github/CODEOWNERS create mode 100644 CHANGELOG.md diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000000..764eb9bf58 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,17 @@ +# Docs: +# - https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners + +# Ideally, we want the following rules: +# - Each normal code review requires an approval from the protocol team +# - Each change to something security-sensitive (lock file or .github folder) requires an approval from the security subteam +# - Each workflow change requires a devops approval +# +# However, there isn't a way for a single file change to require two sets of approvals, +# ... so we ignore devops here, and make it just require a protocol-security-approvers + +# DEFAULT +* @radixdlt/protocol-github-approvers + +# SECURITY-SENSITIVE +/.github/ @radixdlt/protocol-security-approvers +*.lock @radixdlt/protocol-security-approvers diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index c1a1fa9fb7..b60b78bb99 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,21 +1,16 @@ > [!IMPORTANT] > > * Please read our [Contributing Guidelines](/CONTRIBUTING.md) before opening a PR. -> * Before creating your PR, please ensure you read the [branching strategy](/docs/branching-strategy.md). The end result after completing the merge actions should be that `main <= release/XXX <= develop`, where `XXX` is the latest released protocol version. This ensures that we minimise merge conflicts, and that work doesn't go missing. +> * Before creating your PR, please ensure you read the [branching strategy](/docs/branching-strategy.md). The end result after completing the merge actions should be that `release/XXX <= develop`, where `XXX` is the latest released protocol version. This ensures that we minimise merge conflicts, and that work doesn't go missing. > * As per the branching strategy, **you must ensure you select the _correct base branch_**, both for branching from, and in the PR UI above. The following process can be used to decide the base branch: -> * For code changes which can wait until the next protocol update to be released, use `develop`. This should be the default for code changes. -> * For code changes which need to go out as a fully-interoperable update to the node at the current protocol version, use `release/XXX`. +> * For README changes or code changes which can wait until the next protocol update to be released, use `develop`. This should be the default for code changes. +> * For github workflow changes, or code changes which need to go out as a fully-interoperable update to the node at the current protocol version, use `release/XXX`. > * Such changes must be tested and reviewed more carefully to mitigate the risk of regression. > * Once the change is merged, it is the merger's responsibility to ensure `release/XXX` is merged into the `develop` branch. -> * For github workflow changes, use `main`. -> * Once the change is merged, it is the merger's responsibility to ensure `main` is merged into both `release/XXX` and `develop`, so that the changes also apply to hotfixes, and to current development. -> * For changes to README files, use `main`. -> * Once the change is merged, it is the merger's responsibility to ensure `main` is merged into both `release/XXX` and `develop`, so that the changes also apply on these branches. > > _Please remove this section once you confirm you follow its guidance._ ## Summary - ## Testing - + +## Changelog + \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000000..f0b8660540 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,71 @@ + + +# v1.4.x - [Dugong](https://docs.radixdlt.com/docs/dugong) + +## v1.4.0 + +> [!NOTE] +> +> This release is under development. + +### Major Features + +> Headline features that might be called out in the node release overviews + +* *Pending...* + +### Breaking changes + +> Changes which may cause errors for integrators - e.g. deprecation notices or removals to the API interfaces + +* *Pending...* + +### Other changes + +> Other incidental features or changes which shouldn't break existing integrations, but are worthy of mention to node-runners or other interested parties. + +* *Pending...* + +# v1.3.x - [Cuttlefish](https://docs.radixdlt.com/docs/cuttlefish) + +## v1.3.0 + +We didn't have a formal changelog. Please see the [protocol updates](https://docs.radixdlt.com/docs/protocol-updates) section of the docs site for more information. + +# v1.2.x - [Bottlenose](https://docs.radixdlt.com/docs/bottlenose) and before + +We didn't have a formal changelog. Please see the [protocol updates](https://docs.radixdlt.com/docs/protocol-updates) section of the docs site for more information. \ No newline at end of file diff --git a/README.md b/README.md index 5bafd832d2..3075950e4a 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,12 @@ To run a node against our latest test environment, install docker and run `./tes Also check out the [Babylon documentation for exchanges and integrators](https://docs.google.com/document/d/1cjc7_alyzIb2QQIGGn1PEpJyjrMRZYHq3VwkOXRP8J0). +## Branching + +The default branch for this repository is `develop`, which typically includes unreleased code. + +To look at the currently live code, use the corresponding release tag or `release/` branch for the correct [protocol update](https://docs.radixdlt.com/docs/protocol-updates). + ## Subdirectories Here we have: diff --git a/docs/branching-strategy.md b/docs/branching-strategy.md index 8316b9a4d8..519cfca165 100644 --- a/docs/branching-strategy.md +++ b/docs/branching-strategy.md @@ -1,15 +1,13 @@ - # Branching Strategy Once you have read the [contributing guide](../CONTRIBUTING.md), if you want to start development, you will need to know which branches to use. -We use a variant of `git-flow`, where there are three types of base branches: the `main`, `develop`, and `release/*` branches. +We use a variant of `git-flow`, where there are two types of base branches: `develop`, and `release/*` branches. > [!IMPORTANT] > The currently supported base branches are as follows: -> * `develop` - The primary development branch for features and enhancements to be released at the next protocol version. +> * `develop` - The primary development branch for features and enhancements to be released at the next protocol version. It is also the public-facing base branch, which represents the docs and code for the latest official release. > * `release/XXX` = `release/cuttlefish` - The latest published protocol version. This is used for hotfixes or low-risk protocol-compatible changes which will be released as an optional node update. -> * `main` - The public-facing base branch, which represents the docs and code for the latest official release. > > This list is ordered by "each branch should contain every change in each branch below it". When clicking merge on a PR to one of these base branches `B`, it is your duty to ensure that a new PR is raised to merge `B` into all branches above `B` in the list. This ensures that work ends up in the right place, we minimise merge conflicts, and that work doesn't go missing. See the [Development and Merge Process](#developmentmerge-process) section for more information. @@ -18,7 +16,7 @@ We use a variant of `git-flow`, where there are three types of base branches: th When working on changes: * You will first need to select the correct base branch to create your feature branch from. For some epics, it is acceptable to choose a long running `feature/*` or `epic/*` branch as your base, to break up the work into separate reviews, but to merge it atomically once it's been properly tested. * Your branch should start `feature/*`, or variants on naming such as `hotfix/*`, `tweak/*`, `docs/*` are permitted. The specific name should be prefixed by a JIRA ticket or Github issue reference where appropriate, e.g. `feature/NODE-123-my-feature` for JIRA tickets or `feature/gh-1235-my-feature` for github issues. -* When you raise a PR, you will need to ensure you select the appropriate base branch before creating the PR. **The default, `main` is typically not correct!** +* When you raise a PR, you will need to ensure you select the appropriate base branch before creating the PR. Finally, when a PR is merged, it is **the PR merger's responsibility** to ensure that the _base branch_ that was merged into is then merged into _all downstream base branches_. If there is a merge conflict, this should be handled by creating a special `conflict/X-into-Y-DATE` branch (for branches `X`, `Y` and `DATE`) from `X`, and putting in a PR with a merge target of `Y`. If this process is properly followed, such merge conflicts will be rare. @@ -32,17 +30,16 @@ For code changes which need to go out as a fully-interoperable update to the nod ### Stand-alone README changes -Public facing docs change unrelated to another ticket should use a base branch of `main` - as this is the branch which is first visible when someone looks at the repository. Once the change is merged, it is the merger's responsibility to ensure `main` is merged into both `release/XXX` and `develop` branches to avoid merge conflicts or confusion. +Public facing docs change unrelated to another ticket should use a base branch of `develop` - as this is the branch which is first visible when someone looks at the repository. ### Workflow / CI changes -For github workflow changes, start by branching off of and merging to the current `main` branch. +For github workflow changes, start by branching off of and merging to the current `release/XXX` branch. -Once the change is merged, it is the merger's responsibility to ensure `main` is merged into both `release/XXX` and `develop`, so that the changes also apply for current development, and for any hotfixes which need to be built and release. +Once the change is merged, it is the merger's responsibility to ensure `release/XXX` is merged into `develop`, so that the changes also apply for current development, and for any hotfixes which need to be built and release. ## Base branch change process -* When a release is published, as part of the release process, `release/XXX` will get merged into `main`, which should effectively set `main == release/XXX`. * When a new protocol update is about to be published, late in the process: * A `release/YYY` branch will be created from `develop` * Any existing PRs will be reviewed and either have their base branch adjusted to `release/YYY` or kept against `develop` @@ -74,11 +71,11 @@ At merge time, it is acceptable but not recommended to squash-merge. We encourag ### Why do we follow this model? -In order to support a network built upon deterministic execution of the radix engine, we need to have a very clear policy of what is compatible with what. This is where the protocol version strategy comes in. And this maps to git via the `release/*` branch strategy. +In order to support a network built upon deterministic execution of the radix engine, we need to have a very clear policy of what is compatible with what. This is where the protocol version strategy comes in. And this maps to git via the `release/XXX` branch strategy. The rest of the strategy is motivated by the following benefits: * We only have a single PR to review changes on -* We avoid clashes where conflicting PRs are merged into develop and main at the same time (this used to keep happening, particularly with devops workflow changes, and was a pain to resolve) +* We avoid clashes where conflicting PRs are merged into `develop` and `release/XXX` branches at the same time (this used to keep happening, particularly with devops workflow changes, and was a pain to resolve) * We only have one commit for a given change in the commit tree. * It makes it trivial to avoid regressions due to forgetting to merge branches - because we can simply check that all base branches X before Y are entirely merged into Y when a release is prepared.