Modified version of the stacks-core CONTRIBUTING.md
The governing idea behind this monorepo of composite actions can be summarized in a single sentence:
- Make things easier for developers
If there is a way to improve a CI workflow that would benefit other repos in the stacks-network org, it belongs here.
This project and everyone participating in it is governed by this Code of Conduct.
This repo is structured as a typical monorepo, with agnostic composite actions at the top level.
Repository specific composite actions are added at the top level, i.e. ./stacks-core/cargo
.
At a minimum, any new composite actions will need the following 2 files:
action.yml
- The composite action workflow (ex: docker/action.yml)README.md
- How to use the composite action (ex: docker/README.md)
There may or may not be additional folders/logic depending upon the complexity of the workflow, the above 2 files are the minimum requirement.
Branch names should use a prefix that conveys the overall goal of the branch:
feat/some-fancy-new-thing
for a new composite actionfix/some-broken-thing
for hot fixes and bug fixesdocs/something-needs-a-comment
for documentation
PRs from forks or opened by contributors without commit access require some special handling for merging. Any such PR, after being reviewed, must get assigned to a contributor with commit access. This merge-owner is responsible for:
- Creating a new branch in this repository based on the base branch for the PR.
- Retargeting the PR toward the new branch.
- Merging the PR into the new branch.
- Opening a new PR from
new_branch -> original_base
- Tagging reviewers for re-approval.
- Merging the new PR.
Aim to use descriptive git commit messages. We try to follow conventional commits. The general format is as follows:
<type>[optional scope]: <one-line description>
[optional body]
[optional footer(s)]
Common types include build, ci, docs, fix, feat, test, refactor, etc.
When a commit is addressing or related to a particular Github issue, it should reference the issue in the commit message. For example:
fix: incorporate unlocks in mempool admitter, #3623
The most important consideration when accepting or rejecting a contribution is the simplicity (i.e. ease of understanding) of its implementation.
Adding new external package dependencies is very much discouraged. Exceptions will be granted on a case-by-case basis, and only if deemed absolutely necessary.
Additionally, all external dependencies are required to be version locked to a specific commit hash ex:
name: Action
on: push
jobs:
build:
name: Job
runs-on: ubuntu-latest
steps:
## Setup docker buildx
- name: Set up Docker Buildx
id: docker_buildx
uses: docker/setup-buildx-action@d70bba72b1f3fd22344832f00baa16ece964efeb # v3.3.0
Which uses this commit
Although not required, it is encouraged to add a comment for which release an external action is using, i.e. # v3.0.0.
If relevant, all composite workflows should have clearly defined inputs. ex:
inputs:
input-1:
description: "Brief description of what input-1 is"
required: false
default: "sample input"
input-2:
description: "Brief description of what input-2 is"
required: true
default: ""
If relevant, all composite workflows should have clearly defined outputs. example (from stacks-core/cache/bitcoin/action.yml):
outputs:
cache-hit:
description: "Cache Hit"
value: ${{ steps.check_cache.outputs.cache-hit }}
Where check_cache
is the step reporting if a cache already exists.
This repository uses the default github action yaml formatting style. Refer to https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions
Comments are very important for the readability and correctness of the action. The purpose of comments is:
- Allow readers to understand the roles of an operation in the action.
- Allow readers to check the correctness of the action against the comments.