Add branching doc/minor fixes

README.md

@@ -12,7 +12,6 @@ Stacks is a layer-2 blockchain that uses Bitcoin as a base layer for security an
 
 [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg?style=flat)](https://www.gnu.org/licenses/gpl-3.0)
 [![Release](https://img.shields.io/github/v/release/stacks-network/stacks-core?style=flat)](https://github.com/stacks-network/stacks-core/releases/latest)
-[![Build Status](https://github.com/stacks-network/stacks-core/actions/workflows/ci.yml/badge.svg?branch=master&event=workflow_dispatch&style=flat)](https://github.com/stacks-network/stacks-core/actions/workflows/ci.yml?query=event%3Aworkflow_dispatch+branch%3Amaster)
 [![Discord Chat](https://img.shields.io/discord/621759717756370964.svg)](https://stacks.chat)
 
 ## Building

SECURITY.md

@@ -2,7 +2,7 @@
 
 
 ## Supported Versions
-Please see [Releases](https://github.com/stacks-network/stacks-blockchain/releases). It is recommended to use the [most recently released version](https://github.com/stacks-network/stacks-blockchain/releases/latest).
+Please see [Releases](https://github.com/stacks-network/stacks-core/releases). It is recommended to use the [most recently released version](https://github.com/stacks-network/stacks-core/releases/latest).
 
 
 ## Reporting a vulnerability

docs/branching.md

@@ -0,0 +1,35 @@
+# Git Branching
+
+The following is a modified version of the gitflow branching strategy described in <https://nvie.com/posts/a-successful-git-branching-model/>
+
+## Main Branches
+
+- **master** - `origin/master` is the main branch where the source code of HEAD always reflects a production-ready state.
+- **develop** - `origin/develop` is the branch where the source code of HEAD always reflects a state with the latest delivered development changes for the next release.
+- **next** - `origin/next` may contain consensus-breaking changes.
+- **release/X.Y.Z.A.n** is the release branch.
+
+When the source code in the develop branch reaches a stable point and is ready to be released, a release branch is created as `release/X.Y.Z.A.n` (see [release-process.md](./release-process.md)).
+After release, the following will happen:
+
+- `release/X.Y.Z.A.n` branch is merged back to `origin/master`.
+- `origin/master` is then merged into `origin/develop`, and development continues in the `origin/develop` branch.
+- `origin/develop` is then merged into `origin/next`.
+
+## Supporting Branches
+
+Branch names should use a prefix that conveys the overall goal of the branch.
+All branches should be based off of `origin/develop`, with the exception being a hotfix branch which may be based off of `origin/master`.
+
+- `feat/some-fancy-new-thing`: For new features.
+- `fix/some-broken-thing`: For hot fixes and bug fixes.
+- `chore/some-update`: Any non code related change (ex: updating CHANGELOG.md, adding comments to code).
+- `docs/something-needs-a-comment`: For documentation.
+- `ci/build-changes`: For continuous-integration changes.
+- `test/more-coverage`: For branches that only add more tests.
+- `refactor/formatting-fix`: For refactors of the codebase.
+
+The full branch name **must**:
+
+- Have a maximum of 128 characters.
+- Only includes ASCII lowercase and uppercase letters, digits, underscores, periods and dashes.

docs/ci-workflow.md

@@ -1,4 +1,4 @@
-# CI Workflows
+# CI Workflow
 
 All releases are built via a Github Actions workflow named [`CI`](../.github/workflows/ci.yml), and is responsible for:
 
@@ -11,11 +11,11 @@ All releases are built via a Github Actions workflow named [`CI`](../.github/wor
 
 1. Releases are only created when the [CI workflow](../.github/workflows/ci.yml) is triggered against a release branch (ex: `release/X.Y.Z.A.n`).
 2. [Caching](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows) is used to speed up testing - a cache is created based on the type of data (i.e. cargo) and the commit sha.
-   Tests can be retried quickly since the cache will persist until the cleanup job is run.
+   Tests can be retried quickly since the cache will persist until the cleanup job is run or the cache is evicted.
 3. [Nextest](https://nexte.st/) is used to run the tests from a cached build archive file (using commit sha as the cache key).
-   - Two [test archives](https://nexte.st/docs/ci-features/archiving/) are created, one for genesis tests and one for generic tests.
+   - Two [test archives](https://nexte.st/docs/ci-features/archiving/) are created, one for genesis tests and one for non-genesis tests.
    - Unit-tests are [partitioned](https://nexte.st/docs/ci-features/partitioning/) and parallelized to speed up execution time.
-4. Most workflow steps are called from a separate actions repo <https://github.com/stacks-network/actions> to reduce duplication.
+4. Most workflow steps are called from a separate actions repo <https://github.com/stacks-network/actions> to enforce DRY.
 
 ## TL;DR
 
@@ -55,7 +55,7 @@ Partitions (shards) are used when there is a large and unknown number of tests t
 
 There is also a workflow designed to run tests that is manually triggered: [Standalone Tests](../.github/workflows/standalone-tests.yml).
 This workflow requires you to select which test(s) you want to run, which then triggers a reusable workflow via conditional.
-For example, selecting "Epoch Tests" will run the tests defined in [Epoch Tests](../.github/workflows/epoch-tests.yml).
+For example, selecting `Epoch Tests` will run the tests defined in [Epoch Tests](../.github/workflows/epoch-tests.yml).
 Likewise, selecting `Release Tests` will run the same tests as a release workflow.
 
 ### Adding/changing tests
@@ -105,7 +105,7 @@ If any of the tests given to the action (JSON string of `needs` field) fails, th
 
 If you have to mark more than 1 job from the same workflow required in a ruleset, you can use this action in a separate job and only add that job as required.
 
-In the following example, `unit-tests` is a matrix job with 8 partitions (i.e. 8 jobs are running), while the others are normal jobs.
+In the following example, `unit-tests` is a matrix job from [Stacks Core Tests](../.github/workflows/stacks-core-tests.yml) with 8 partitions (i.e. 8 jobs are running), while the others are normal jobs.
 If any of the jobs are failing, the `check-tests` job will also fail.
 
 ```yaml
@@ -145,7 +145,7 @@ check-tests:
 ### Merging a branch to develop
 
 Once a PR is added to the merge queue, the target branch is merged into the source branch.
-Then, the same workflows are triggered as in the [previous step](#opening-a-pr-against-develop).
+Then, the same workflows are triggered as in the [previous step](#openingupdating-a-pr).
 
 ---
 

docs/mining.md

@@ -1,7 +1,7 @@
 # Stacks Mining
 
 Stacks tokens (STX) are mined by transferring BTC via PoX. To run as a miner,
-you should make sure to add the following config fields to your config file:
+you should make sure to add the following config fields to your [config file](../testnet/stacks-node/conf/mainnet-miner-conf.toml):
 
 ```toml
 [node]
@@ -80,4 +80,4 @@ Estimates are then randomly "fuzzed" using uniform random fuzz of size up to
 ## Further Reading
 
 - [stacksfoundation/miner-docs](https://github.com/stacksfoundation/miner-docs)
-- [Mining Documentation](https://docs.stacks.co/docs/nodes-and-miners/miner-mainnet)
+- [Mining Documentation](https://docs.stacks.co/stacks-in-depth/nodes-and-miners/mine-mainnet-stacks-tokens)

docs/profiling.md

@@ -9,7 +9,7 @@ This document describes several techniques to profile (i.e. find performance bot
 - generating flame graphs, and
 - profiling sqlite queries.
 
-Note that all bash commands in this document are run from the stacks-blockchain repository root directory.
+Note that all bash commands in this document are run from the [stacks-core repository](https://github.com/stacks-network/stacks-core) root directory.
 
 ## Logging tips
 

docs/release-process.md

@@ -14,8 +14,8 @@
 ## Release Schedule and Hotfixes
 
 Normal releases in this repository that add new features are released on a monthly schedule.
-The currently staged changes for such releases are in the [develop branch](https://github.com/stacks-network/stacks-blockchain/tree/develop).
-It is generally safe to run a `stacks-node` from that branch, though it has received less rigorous testing than release tags.
+The currently staged changes for such releases are in the [develop branch](https://github.com/stacks-network/stacks-core/tree/develop).
+It is generally safe to run a `stacks-node` from that branch, though it has received less rigorous testing than release tags or the [master branch](https://github.com/stacks-network/stacks-core/tree/master).
 If bugs are found in the `develop` branch, please do [report them as issues](https://github.com/stacks-network/stacks-core/issues) on this repository.
 
 For fixes that impact the correct functioning or liveness of the network, _hotfixes_ may be issued.
@@ -40,7 +40,7 @@ A increments on non-consensus-breaking changes that do not require a fresh chain
 n increments on patches and hot-fixes (akin to semantic PATCH)
 ```
 
-Optionally, an extra pre-release field may be appended to the version to specify a release candidate in the format `-rc[0-9]`
+Optionally, an extra pre-release field may be appended to the version to specify a release candidate in the format `-rc[0-9]`.
 
 ## Non-Consensus Breaking Release Process
 
@@ -50,31 +50,32 @@ A release should happen at least 24 hours before the start of a new cycle, to av
 
 1. Before creating the release, the _version number_ must be determined, where the factors that determine the version number are discussed in [Versioning](#versioning).
 
-   1. First determine whether there are any "non-consensus-breaking changes that require a fresh chainstate".
+   - First determine whether there are any "non-consensus-breaking changes that require a fresh chainstate".
       - In other words, the database schema has changed, but an automatic migration was not implemented.
       - Determine whether this a feature release, as opposed to a hotfix or a patch.
-   2. A new branch in format `release/X.Y.Z.A.n` is created from the base branch `develop`.
+   - A new branch in the format `release/X.Y.Z.A.n` is created from the base branch `develop`.
 
 2. Enumerate PRs and/or issues that would _block_ the release.
 
-   1. A label should be applied to each such issue/PR as `X.Y.Z.A.n-blocker`.
+   - A label should be applied to each such issue/PR as `X.Y.Z.A.n-blocker`.
 
-3. Since development is continuing in the `develop` branch, it may be necessary to cherry-pick commits into the release branch.
+3. Since development is continuing in the `develop` branch, it may be necessary to cherry-pick some commits into the release branch.
 
-   1. Create a feature branch from `release/X.Y.Z.A.n`, ex: `feat/X.Y.Z.A.n-pr_number`.
-   2. Add cherry-picked commits to the `feat/X.Y.Z.A.n-pr_number` branch
-   3. Merge `feat/X.Y.Z.A.n-pr_number` back into `release/X.Y.Z.A.n`.
+   - Create a feature branch from `release/X.Y.Z.A.n`, ex: `feat/X.Y.Z.A.n-pr_number`.
+   - Add cherry-picked commits to the `feat/X.Y.Z.A.n-pr_number` branch
+   - Merge `feat/X.Y.Z.A.n-pr_number` into `release/X.Y.Z.A.n`.
 
 4. Open a PR to update the `CHANGELOG.md` file in the `release/X.Y.Z.A.n` branch.
 
-   1. Create a chore branch from `release/X.Y.Z.A.n`, ex: `chore/X.Y.Z.A.n-changelog`.
-   2. Add summaries of all Pull Requests to the `Added`, `Changed` and `Fixed` sections.
+   - Create a chore branch from `release/X.Y.Z.A.n`, ex: `chore/X.Y.Z.A.n-changelog`.
+   - Add summaries of all Pull Requests to the `Added`, `Changed` and `Fixed` sections.
       - Pull requests merged into `develop` can be found [here](https://github.com/stacks-network/stacks-core/pulls?q=is%3Apr+is%3Aclosed+base%3Adevelop+sort%3Aupdated-desc).
-        - **Note**: GitHub does not allow sorting by _merge time_, so, when sorting by some proxy criterion, some care should be used to understand which PR's were _merged_ after the last release.
+
+        **Note**: GitHub does not allow sorting by _merge time_, so, when sorting by some proxy criterion, some care should be used to understand which PR's were _merged_ after the last release.
 
-5. Once `chore/X.Y.Z.A.n-changelog` has merged, a build may be started by manually triggering the [`CI` Github Actions workflow](https://github.com/stacks-network/stacks-core/actions/workflows/ci.yml) against the `release/X.Y.Z.A.n` branch.
+5. Once `chore/X.Y.Z.A.n-changelog` has merged, a build may be started by manually triggering the [`CI` workflow](../.github/workflows/ci.yml) against the `release/X.Y.Z.A.n` branch.
 
-6. Once the release has been built and binaries are available, ecosystem participants shall be notified to test the tagged release on various staging infrastructure.
+6. Once the release candidate has been built and binaries are available, ecosystem participants shall be notified to test the tagged release on various staging infrastructure.
 
 7. The release candidate will tested that it successfully syncs with the current chain from genesis both in testnet and mainnet.
 
@@ -87,13 +88,12 @@ A release should happen at least 24 hours before the start of a new cycle, to av
    Announcements will then be shared in the `#stacks-core-devs` channel in the Stacks Discord, as well as the [mailing list](https://groups.google.com/a/stacks.org/g/announce).
 
 10. Finally, the following merges will happen to complete the release process:
-    1. Release branch `release/X.Y.Z.A.n` will be merged into the `master` branch.
-    2. Then, `master` will be merged back into `develop`.
+    - Release branch `release/X.Y.Z.A.n` will be merged into the `master` branch.
+    - Then, `master` will be merged into `develop`.
 
 ## Consensus Breaking Release Process
 
 Consensus breaking releases shall follow the same overall process as a non-consensus release, with the following considerations:
 
 - The release must be timed so that sufficient time is given to perform a genesis sync.
 - The release must take into account the activation height at which the new consensus rules will take effect.
-  Generically, a few weeks lead time is required for consensus breaking changes.

testnet/stacks-node/conf/mainnet-miner-conf.toml

@@ -7,8 +7,7 @@ prometheus_bind = "127.0.0.1:9153"
 seed = "<YOUR_SEED>"
 local_peer_seed = "<YOUR_SEED>"
 miner = true
-# Disable microblocks (ref: https://github.com/stacks-network/stacks-core/pull/4561 )
-mine_microblocks = false
+mine_microblocks = false # Disable microblocks (ref: https://github.com/stacks-network/stacks-core/pull/4561 )
 
 [burnchain]
 chain = "bitcoin"

testnet/stacks-node/conf/testnet-follower-conf.toml

@@ -38,32 +38,32 @@ start_height = 0
 
 [[burnchain.epochs]]
 epoch_name = "2.0"
-start_height = 0
+start_height = 230
 
 [[burnchain.epochs]]
 epoch_name = "2.05"
-start_height = 1
+start_height = 240
 
 [[burnchain.epochs]]
 epoch_name = "2.1"
-start_height = 2
+start_height = 240
 
 [[burnchain.epochs]]
 epoch_name = "2.2"
-start_height = 3
+start_height = 241
 
 [[burnchain.epochs]]
 epoch_name = "2.3"
-start_height = 4
+start_height = 242
 
 [[burnchain.epochs]]
 epoch_name = "2.4"
-start_height = 5
+start_height = 243
 
 [[burnchain.epochs]]
 epoch_name = "2.5"
-start_height = 6
+start_height = 244
 
 [[burnchain.epochs]]
 epoch_name = "3.0"
-start_height = 2000701
+start_height = 2_000_250