Skip to content

Commit bd35a46

Browse files
wileyjwileyj
committed
update documentation
1 parent dec3010 commit bd35a46

File tree

2 files changed

+95
-48
lines changed

2 files changed

+95
-48
lines changed

‎.github/PULL_REQUEST_TEMPLATE.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,17 +3,19 @@
33
Pull requests are ideal for making small changes to this project. However, they are NOT an appropriate venue to introducing non-trivial or breaking changes to the codebase.
44
55
For introducing non-trivial or breaking changes to the codebase, please follow the SIP (Stacks Improvement Proposal) process documented here:
6-
https://github.com/blockstack/stacks-blockchain/blob/master/sip/sip-000-stacks-improvement-proposal-process.md.
6+
https://github.com/stacksgov/sips/blob/main/sips/sip-000/sip-000-stacks-improvement-proposal-process.md.
77
-->
88

99
### Description
1010

1111
### Applicable issues
12+
1213
- fixes #
1314

1415
### Additional info (benefits, drawbacks, caveats)
1516

1617
### Checklist
18+
1719
- [ ] Test coverage for new or modified code paths
1820
- [ ] Changelog is updated
1921
- [ ] Required documentation changes (e.g., `docs/rpc/openapi.yaml` and `rpc-endpoints.md` for v2 endpoints, `event-dispatcher.md` for new events)

‎docs/ci-release.md

Lines changed: 92 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -1,58 +1,62 @@
11
# Releases
22

3-
All releases are built via a Github Actions workflow named `CI`, and is responsible for building binary archives, checksums, and resulting docker images.
4-
This workflow will also trigger any tests that need to be run, like integration tests.
3+
All releases are built via a Github Actions workflow named `CI` ([ci.yml](../.github/workflows/ci.yml)), and is responsible for:
54

6-
1. Releases are only created if a tag is **manually** provided when the ci workflow is triggered.
7-
2. Pushing a new feature branch: Nothing is triggered automatically. A PR is required, or the ci workflow can be triggered manually on a specific branch to build a docker image (and run the standard PR tests) for the specified branch.
8-
3. Caching 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.
9-
4. [nextest](https://nexte.st/) is used to run the tests from an archived file that is cached (using commit sha as a key))
5+
- Verifying code is formatted correctly
6+
- Building binary archives and checksums
7+
- Docker images
8+
- Triggering tests conditionally (different tests run for a release vs a PR)
9+
10+
1. Releases are only created if a tag is **manually** provided when the [CI workflow](../.github/workflows/ci.yml) is triggered.
11+
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.
12+
3. [nextest](https://nexte.st/) is used to run the tests from an archived file that is cached (using commit sha as a key))
1013
- Two [archives](https://nexte.st/book/reusing-builds.html) are created, one for genesis tests and one for generic tests (it is done this way to reduce the time spent building)
1114
- Unit-tests are [partitioned](https://nexte.st/book/partitioning.html) and multi-threaded to speed up execution time
1215

1316
## TL;DR
1417

15-
1. An open/re-opened/synchronized PR will produce a single image built from source on Debian with glibc with 2 tags:
16-
- `stacks-blockchain:<branch-name>`
17-
- `stacks-blockchain:<pr-number>`
18-
2. A merged PR from `develop` to the default branch will produce a single image built from source on Debian with glibc:
19-
- `stacks-blockchain:<default-branch-name>`
20-
3. An untagged build of any branch will produce a single image built from source on Debian with glibc:
21-
- `stacks-blockchain:<branch-name>`
22-
4. A tagged release on a non-default branch will produces:
23-
- Docker Alpine image for several architectures tagged with:
24-
- `stacks-blockchain:<x.x.x.x.x>`
25-
- Docker Debian image for several architectures tagged with:
26-
- `stacks-blockchain:<x.x.x.x.x-debian>`
27-
5. A tagged release on the default branch will produce:
28-
- Github Release of the specified tag with:
29-
- Binary archives for several architectures
30-
- Docker Alpine image for several architectures tagged with:
31-
- `stacks-blockchain:<x.x.x.x.x>`
32-
- `stacks-blockchain:<latest>`
33-
- Docker Debian image for several architectures tagged with:
34-
- `stacks-blockchain:<x.x.x.x.x-debian>`
35-
- `stacks-blockchain:<latest-debian>`
18+
- Pushing a feature branch will not trigger a workflow
19+
- An open/re-opened/synchronized PR will produce a single image built from source on Debian with glibc with 2 tags:
20+
- `stacks-core:<branch-name>`
21+
- `stacks-core:<pr-number>`
22+
- A merged PR into `default-branch` from `develop` will produce a single image built from source on Debian with glibc:
23+
- `stacks-core:<default-branch-name>`
24+
- An untagged build of any branch will produce a single image built from source on Debian with glibc:
25+
- `stacks-core:<branch-name>`
26+
- A tagged release on a non-default branch will produces:
27+
- Docker Alpine image for several architectures tagged with:
28+
- `stacks-core:<x.x.x.x.x>`
29+
- Docker Debian image for several architectures tagged with:
30+
- `stacks-core:<x.x.x.x.x-debian>`
31+
- A tagged release on the default branch will produce:
32+
- Github Release of the specified tag with:
33+
- Binary archives for several architectures
34+
- Docker Alpine image for several architectures tagged with:
35+
- `stacks-core:<x.x.x.x.x>`
36+
- `stacks-core:<latest>`
37+
- Docker Debian image for several architectures tagged with:
38+
- `stacks-core:<x.x.x.x.x-debian>`
39+
- `stacks-core:<latest-debian>`
3640

3741
## Release workflow
3842

3943
1. Create a feature branch: `feat/fix-something`
4044
2. PR `feat/fix-something` to the `develop` branch where the PR is numbered `112`
4145
1. Docker image tagged with the **branch name** and **PR number**
4246
- ex:
43-
- `stacks-blockchain:feat-fix-something`
44-
- `stacks-blockchain:pr-112`
47+
- `stacks-core:feat-fix-something`
48+
- `stacks-core:pr-112`
4549
2. CI tests are run
4650
3. PR `develop` to the default branch where the PR is numbered `112`
4751
1. Docker image tagged with the **branch name** and **PR number**
4852
- ex:
49-
- `stacks-blockchain:feat-fix-something`
50-
- `stacks-blockchain:pr-112`
53+
- `stacks-core:feat-fix-something`
54+
- `stacks-core:pr-112`
5155
2. CI tests are run
5256
4. Merge `develop` branch to the default branch
5357
1. Docker image is tagged with the **default branch** `master`
5458
- ex:
55-
- `stacks-blockchain:master`
59+
- `stacks-core:master`
5660
2. CI tests are run
5761
5. CI workflow is manually triggered on **non-default branch** with a version, i.e. `2.1.0.0.0-rc0`
5862
1. No Docker images/binaries are created
@@ -62,10 +66,10 @@ This workflow will also trigger any tests that need to be run, like integration
6266
2. All release tests are run
6367
3. Docker image pushed with tags of the **input version** and **latest**
6468
- ex:
65-
- `stacks-blockchain:2.1.0.0.0-debian`
66-
- `stacks-blockchain:latest-debian`
67-
- `stacks-blockchain:2.1.0.0.0`
68-
- `stacks-blockchain:latest`
69+
- `stacks-core:2.1.0.0.0-debian`
70+
- `stacks-core:latest-debian`
71+
- `stacks-core:2.1.0.0.0`
72+
- `stacks-core:latest`
6973

7074
## Tests
7175

@@ -79,7 +83,7 @@ There are also 2 different methods in use with regard to running tests:
7983
A matrix is used when there are several known tests that need to be run. Partitions (shards) are used when there is a large and unknown number of tests to run (ex: `cargo test` to run all tests).
8084

8185
There is also a workflow designed to run tests that are manually triggered: [Standalone Tests](../.github/workflows/standalone-tests.yml).
82-
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). Likewise, selecting `Release Tests` will run the same tests as a release workflow.
86+
This workflow requires you to select which test(s) you want to run, which then triggers a reusbale workflow via conditional. 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.
8387

8488
Files:
8589

@@ -90,6 +94,47 @@ Files:
9094
- [Epoch Tests](../.github/workflows/epoch-tests.yml)
9195
- [Slow Tests](../.github/workflows/slow-tests.yml)
9296

97+
### Adding/changing tests
98+
99+
With the exception of `unit-tests` in [Stacks Blockchain Tests](../.github/workflows/stacks-blockchain-tests.yml), adding/removing a test requires a change to the workflow matrix. Example from [Atlas Tests](../.github/workflows/atlas-tests.yml):
100+
101+
```yaml
102+
atlas-tests:
103+
name: Atlas Test
104+
runs-on: ubuntu-latest
105+
strategy:
106+
## Continue with the test matrix even if we've had a failure
107+
fail-fast: false
108+
## Run a maximum of 2 concurrent tests from the test matrix
109+
max-parallel: 2
110+
matrix:
111+
test-name:
112+
- tests::neon_integrations::atlas_integration_test
113+
- tests::neon_integrations::atlas_stress_integration_test
114+
```
115+
116+
Example of adding a new test `tests::neon_integrations::atlas_new_test`:
117+
118+
```yaml
119+
...
120+
matrix:
121+
test-name:
122+
- tests::neon_integrations::atlas_integration_test
123+
- tests::neon_integrations::atlas_stress_integration_test
124+
- tests::neon_integrations::atlas_new_test
125+
```
126+
127+
The separation of tests (outside of [Slow Tests](../.github/workflows/slow-tests.yml)) is performed by creating a separate workflow for each _type_ of test that is being run. Using the example above, to add/remove any tests from being run - the `matrix` will need to be adjusted.
128+
129+
ex:
130+
131+
- `Atlas Tests`: Tests related to Atlas
132+
- `Bitcoin Tests`: Tests relating to burnchain operations
133+
- `Epoch Tests`: Tests related to epoch changes
134+
- `Slow Tests`: These tests have been identified as taking longer than others. The threshold used is if a test takes longer than `10 minutes` to complete successfully (or times out semi-regularly), it should be added here.
135+
- `Stacks Blockchain Tests`:
136+
- `full-genesis`: Tests related to full genesis
137+
93138
## Triggering a workflow
94139

95140
### PR a branch to develop
@@ -102,8 +147,8 @@ ex: Branch is named `feat/fix-something` and the PR is numbered `112`
102147
- [Bitcoin Tests](../.github/workflows/bitcoin-tests.yml)
103148
- [Docker image](../.github/workflows/image-build-source.yml) is built from source on a debian distribution and pushed with the branch name and PR number as tags
104149
- ex:
105-
- `stacks-blockchain:feat-fix-something`
106-
- `stacks-blockchain:pr-112`
150+
- `stacks-core:feat-fix-something`
151+
- `stacks-core:pr-112`
107152

108153
---
109154

@@ -123,8 +168,8 @@ ex: Branch is named `develop` and the PR is numbered `113`
123168
- [Bitcoin Tests](../.github/workflows/bitcoin-tests.yml)
124169
- [Docker image](../.github/workflows/image-build-source.yml) is built from source on a debian distribution and pushed with the branch name and PR number as tags
125170
- ex:
126-
- `stacks-blockchain:develop`
127-
- `stacks-blockchain:pr-113`
171+
- `stacks-core:develop`
172+
- `stacks-core:pr-113`
128173

129174
---
130175

@@ -136,7 +181,7 @@ ex: Branch is named `develop` and the PR is numbered `113`
136181
- [Bitcoin Tests](../.github/workflows/bitcoin-tests.yml)
137182
- [Docker image](../.github/workflows/image-build-source.yml) is built from source on a debian distribution and pushed with the branch name as a tag
138183
- ex:
139-
- `stacks-blockchain:master`
184+
- `stacks-core:master`
140185

141186
---
142187

@@ -148,7 +193,7 @@ ex: Branch is named `develop` and the PR is numbered `113`
148193
- [Bitcoin Tests](../.github/workflows/bitcoin-tests.yml)
149194
- [Docker image](../.github/workflows/image-build-source.yml) is built from source on a debian distribution and pushed with the branch name as a tag
150195
- ex:
151-
- `stacks-blockchain:<branch name>`
196+
- `stacks-core:<branch name>`
152197

153198
---
154199

@@ -178,9 +223,9 @@ ex: Branch is named `develop` and the PR is numbered `113`
178223
- [Github release](../.github/workflows/github-release.yml) (with artifacts/checksum) is created using the manually input tag
179224
- [Docker image](../.github/workflows/image-build-binary.yml) built from binaries on debian/alpine distributions and pushed with the provided input tag and `latest`
180225
- ex:
181-
- `stacks-blockchain:2.1.0.0.0-debian`
182-
- `stacks-blockchain:latest-debian`
183-
- `stacks-blockchain:2.1.0.0.0`
184-
- `stacks-blockchain:latest`
226+
- `stacks-core:2.1.0.0.0-debian`
227+
- `stacks-core:latest-debian`
228+
- `stacks-core:2.1.0.0.0`
229+
- `stacks-core:latest`
185230

186231
---

0 commit comments

Comments
 (0)