kylefang/stacks-puppet-node
1
0
Fork 0
mirror of https://github.com/alexgo-io/stacks-puppet-node.git synced 2026-01-12 22:43:42 +08:00
Code Issues Packages Projects Releases Wiki Activity

update documentation

Browse Source
This commit is contained in:
wileyj
2023-11-28 20:11:31 -08:00
parent dec30101de
commit bd35a46bbc
2 changed files with 95 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
.github/PULL_REQUEST_TEMPLATE.md vendored
View File

@@ -3,17 +3,19 @@
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.
For introducing non-trivial or breaking changes to the codebase, please follow the SIP (Stacks Improvement Proposal) process documented here:
https://github.com/blockstack/stacks-blockchain/blob/master/sip/sip-000-stacks-improvement-proposal-process.md.
https://github.com/stacksgov/sips/blob/main/sips/sip-000/sip-000-stacks-improvement-proposal-process.md.
-->
### Description
### Applicable issues
- fixes #
### Additional info (benefits, drawbacks, caveats)
### Checklist
- [ ] Test coverage for new or modified code paths
- [ ] Changelog is updated
- [ ] Required documentation changes (e.g., `docs/rpc/openapi.yaml` and `rpc-endpoints.md` for v2 endpoints, `event-dispatcher.md` for new events)

139
docs/ci-release.md
View File

@@ -1,38 +1,42 @@
# Releases
All releases are built via a Github Actions workflow named `CI`, and is responsible for building binary archives, checksums, and resulting docker images.
This workflow will also trigger any tests that need to be run, like integration tests.
All releases are built via a Github Actions workflow named `CI` ([ci.yml](../.github/workflows/ci.yml)), and is responsible for:
1. Releases are only created if a tag is **manually** provided when the ci workflow is triggered.
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.
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.
4. [nextest](https://nexte.st/) is used to run the tests from an archived file that is cached (using commit sha as a key))
- Verifying code is formatted correctly
- Building binary archives and checksums
- Docker images
- Triggering tests conditionally (different tests run for a release vs a PR)
1. Releases are only created if a tag is **manually** provided when the [CI workflow](../.github/workflows/ci.yml) is triggered.
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.
3. [nextest](https://nexte.st/) is used to run the tests from an archived file that is cached (using commit sha as a key))
- 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)
- Unit-tests are [partitioned](https://nexte.st/book/partitioning.html) and multi-threaded to speed up execution time
## TL;DR
1. An open/re-opened/synchronized PR will produce a single image built from source on Debian with glibc with 2 tags:
- `stacks-blockchain:<branch-name>`
- `stacks-blockchain:<pr-number>`
2. A merged PR from `develop` to the default branch will produce a single image built from source on Debian with glibc:
- `stacks-blockchain:<default-branch-name>`
3. An untagged build of any branch will produce a single image built from source on Debian with glibc:
- `stacks-blockchain:<branch-name>`
4. A tagged release on a non-default branch will produces:
- Docker Alpine image for several architectures tagged with:
- `stacks-blockchain:<x.x.x.x.x>`
- Docker Debian image for several architectures tagged with:
- `stacks-blockchain:<x.x.x.x.x-debian>`
5. A tagged release on the default branch will produce:
- Github Release of the specified tag with:
- Binary archives for several architectures
- Docker Alpine image for several architectures tagged with:
- `stacks-blockchain:<x.x.x.x.x>`
- `stacks-blockchain:<latest>`
- Docker Debian image for several architectures tagged with:
- `stacks-blockchain:<x.x.x.x.x-debian>`
- `stacks-blockchain:<latest-debian>`
- Pushing a feature branch will not trigger a workflow
- An open/re-opened/synchronized PR will produce a single image built from source on Debian with glibc with 2 tags:
- `stacks-core:<branch-name>`
- `stacks-core:<pr-number>`
- A merged PR into `default-branch` from `develop` will produce a single image built from source on Debian with glibc:
- `stacks-core:<default-branch-name>`
- An untagged build of any branch will produce a single image built from source on Debian with glibc:
- `stacks-core:<branch-name>`
- A tagged release on a non-default branch will produces:
- Docker Alpine image for several architectures tagged with:
- `stacks-core:<x.x.x.x.x>`
- Docker Debian image for several architectures tagged with:
- `stacks-core:<x.x.x.x.x-debian>`
- A tagged release on the default branch will produce:
- Github Release of the specified tag with:
- Binary archives for several architectures
- Docker Alpine image for several architectures tagged with:
- `stacks-core:<x.x.x.x.x>`
- `stacks-core:<latest>`
- Docker Debian image for several architectures tagged with:
- `stacks-core:<x.x.x.x.x-debian>`
- `stacks-core:<latest-debian>`
## Release workflow
@@ -40,19 +44,19 @@ This workflow will also trigger any tests that need to be run, like integration
2. PR `feat/fix-something` to the `develop` branch where the PR is numbered `112`
1. Docker image tagged with the **branch name** and **PR number**
- ex:
- `stacks-blockchain:feat-fix-something`
- `stacks-blockchain:pr-112`
- `stacks-core:feat-fix-something`
- `stacks-core:pr-112`
2. CI tests are run
3. PR `develop` to the default branch where the PR is numbered `112`
1. Docker image tagged with the **branch name** and **PR number**
- ex:
- `stacks-blockchain:feat-fix-something`
- `stacks-blockchain:pr-112`
- `stacks-core:feat-fix-something`
- `stacks-core:pr-112`
2. CI tests are run
4. Merge `develop` branch to the default branch
1. Docker image is tagged with the **default branch** `master`
- ex:
- `stacks-blockchain:master`
- `stacks-core:master`
2. CI tests are run
5. CI workflow is manually triggered on **non-default branch** with a version, i.e. `2.1.0.0.0-rc0`
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
2. All release tests are run
3. Docker image pushed with tags of the **input version** and **latest**
- ex:
- `stacks-blockchain:2.1.0.0.0-debian`
- `stacks-blockchain:latest-debian`
- `stacks-blockchain:2.1.0.0.0`
- `stacks-blockchain:latest`
- `stacks-core:2.1.0.0.0-debian`
- `stacks-core:latest-debian`
- `stacks-core:2.1.0.0.0`
- `stacks-core:latest`
## Tests
@@ -79,7 +83,7 @@ There are also 2 different methods in use with regard to running tests:
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).
There is also a workflow designed to run tests that are 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). Likewise, selecting `Release Tests` will run the same tests as a release workflow.
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.
Files:
@@ -90,6 +94,47 @@ Files:
- [Epoch Tests](../.github/workflows/epoch-tests.yml)
- [Slow Tests](../.github/workflows/slow-tests.yml)
### Adding/changing tests
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):
```yaml
atlas-tests:
name: Atlas Test
runs-on: ubuntu-latest
strategy:
## Continue with the test matrix even if we've had a failure
fail-fast: false
## Run a maximum of 2 concurrent tests from the test matrix
max-parallel: 2
matrix:
test-name:
- tests::neon_integrations::atlas_integration_test
- tests::neon_integrations::atlas_stress_integration_test
```
Example of adding a new test `tests::neon_integrations::atlas_new_test`:
```yaml
...
matrix:
test-name:
- tests::neon_integrations::atlas_integration_test
- tests::neon_integrations::atlas_stress_integration_test
- tests::neon_integrations::atlas_new_test
```
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.
ex:
- `Atlas Tests`: Tests related to Atlas
- `Bitcoin Tests`: Tests relating to burnchain operations
- `Epoch Tests`: Tests related to epoch changes
- `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.
- `Stacks Blockchain Tests`:
- `full-genesis`: Tests related to full genesis
## Triggering a workflow
### PR a branch to develop
@@ -102,8 +147,8 @@ ex: Branch is named `feat/fix-something` and the PR is numbered `112`
- [Bitcoin Tests](../.github/workflows/bitcoin-tests.yml)
- [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
- ex:
- `stacks-blockchain:feat-fix-something`
- `stacks-blockchain:pr-112`
- `stacks-core:feat-fix-something`
- `stacks-core:pr-112`
---
@@ -123,8 +168,8 @@ ex: Branch is named `develop` and the PR is numbered `113`
- [Bitcoin Tests](../.github/workflows/bitcoin-tests.yml)
- [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
- ex:
- `stacks-blockchain:develop`
- `stacks-blockchain:pr-113`
- `stacks-core:develop`
- `stacks-core:pr-113`
---
@@ -136,7 +181,7 @@ ex: Branch is named `develop` and the PR is numbered `113`
- [Bitcoin Tests](../.github/workflows/bitcoin-tests.yml)
- [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
- ex:
- `stacks-blockchain:master`
- `stacks-core:master`
---
@@ -148,7 +193,7 @@ ex: Branch is named `develop` and the PR is numbered `113`
- [Bitcoin Tests](../.github/workflows/bitcoin-tests.yml)
- [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
- ex:
- `stacks-blockchain:<branch name>`
- `stacks-core:<branch name>`
---
@@ -178,9 +223,9 @@ ex: Branch is named `develop` and the PR is numbered `113`
- [Github release](../.github/workflows/github-release.yml) (with artifacts/checksum) is created using the manually input tag
- [Docker image](../.github/workflows/image-build-binary.yml) built from binaries on debian/alpine distributions and pushed with the provided input tag and `latest`
- ex:
- `stacks-blockchain:2.1.0.0.0-debian`
- `stacks-blockchain:latest-debian`
- `stacks-blockchain:2.1.0.0.0`
- `stacks-blockchain:latest`
- `stacks-core:2.1.0.0.0-debian`
- `stacks-core:latest-debian`
- `stacks-core:2.1.0.0.0`
- `stacks-core:latest`
---