Skip to content

Commit 4015e5f

Browse files
niheconomoumniheconomoum
committed
docs: simplify contributor guidance
1 parent 74a8473 commit 4015e5f

File tree

1 file changed

+74
-65
lines changed

1 file changed

+74
-65
lines changed

‎README.md‎

Lines changed: 74 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -22,99 +22,108 @@ For outstanding `satosa` image PRs, check [PRs with the "library/satosa" label o
2222

2323
---
2424

25-
## Coding Style
26-
27-
Please follow the style of the other Docker Official Images. In particular, use tabs for indentation instead of spaces.
25+
# Contributing
2826

29-
## Git Commit Messages
27+
This project uses the [Git feature branch workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow). Please submit your changes for review as a [GitHub pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests).
3028

31-
Please follow [Angular Commit Message Conventions](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#commit). The following scopes are currently in use:
32-
- **docker-entrypoint**: the Dockerfile ENTRYPOINT scripts; currently only [docker-entrypoint.sh](docker-entrypoint.sh)
33-
- **docker-library**: the Docker Official Images library entry generator; currently only [generate-stackbrew-library.sh](generate-stackbrew-library.sh)
34-
- **dockerfile-linux**: all Linux variants of the container image itself; includes [Dockerfile-linux.template](Dockerfile-linux.template) and the corresponding Linux variant image definitions in the SATOSA version-specific directories, e.g., **8.2/bullseye/Dockerfile**
35-
- **dockerfile-windows**: currently unused
36-
- **git**: Git repository configuration or GitHub-specific files; includes [.gitignore](.gitignore), [.gitattributes](.gitattributes), and [the GitHub Actions workflows](.github/workflows)
37-
- **license**: software licensing information; currently only [LICENSE.md](LICENSE.md)
38-
- **readme**: this file
39-
- **templating**: the gawk/jq-based templating engine itself, as opposed to the templates; currently only [apply-templates.sh](apply-templates.sh)
40-
- **update**: a helper script that executes both the version tracker and templating engine; currently only [update.sh](update.sh)
41-
- **versions**: the SATOSA version tracker; includes [versions.sh](versions.sh) and [versions.json](versions.json)
29+
In forks of this repository, enable the GitHub Actions workflows. GitHub Actions runs two workflows when developers push commits to a branch. [Verify Templating](actions/workflows/verify-templating.yml) checks for uncommitted changes. [GitHub CI](actions/workflows/ci.yml) builds and tests the container images.
4230

4331
## Development Environment
4432

45-
To develop Docker Official Images, please install [bashbrew](https://github.com/docker-library/bashbrew), the Docker Official Images build tool:
46-
```bash
47-
git clone --depth=1 https://github.com/docker-library/bashbrew; \
48-
( \
49-
umask 0022; \
50-
cd bashbrew; \
51-
go mod download; \
52-
./bashbrew.sh --version; \
53-
sudo cp bin/bashbrew /usr/local/bin/ \
54-
); \
55-
rm -rf bashbrew
56-
```
57-
Bashbrew uses [manifest-tool](https://github.com/estesp/manifest-tool) to generate the shared tag index:
58-
```bash
59-
git clone --depth=1 https://github.com/estesp/manifest-tool; \
60-
( \
61-
umask 0022; \
62-
cd manifest-tool; \
63-
make binary; \
64-
sudo cp manifest-tool /usr/local/bin/ \
65-
); \
66-
rm -rf manifest-tool
67-
```
68-
Please make note of these tools' dependencies, in particular [GNU Make](https://www.gnu.org/software/make/) and [Go](https://go.dev/).
69-
70-
The templating engine and version tracker require [GNU awk](https://www.gnu.org/software/gawk/), [GNU Find Utilities](https://www.gnu.org/software/findutils/), [GNU Wget](https://www.gnu.org/software/wget/), and [jq](https://stedolan.github.io/jq/).
71-
72-
Use [qemu-user-static](https://github.com/multiarch/qemu-user-static) to work with multi-architecture containers.
73-
74-
In forks of this repository, enable both GitHub Actions and the GitHub CI workflow after reviewing the workflow definitions.
33+
This project uses the following software:
34+
35+
- [Docker 20.10 or newer](https://docs.docker.com/engine/install/)
36+
37+
- [GNU awk](https://www.gnu.org/software/gawk/), [GNU Find Utilities](https://www.gnu.org/software/findutils/), [GNU Wget](https://www.gnu.org/software/wget/), and [jq](https://stedolan.github.io/jq/), for the templating engine and version tracker
38+
39+
- [GNU Make](https://www.gnu.org/software/make/) and [Go](https://go.dev/), required by bashbrew and manifest-tool
40+
41+
- [bashbrew](https://github.com/docker-library/bashbrew), the Docker Official Images build tool
42+
43+
- [manifest-tool](https://github.com/estesp/manifest-tool), which generates the shared tag index
44+
45+
- (optional) [qemu-user-static](https://github.com/multiarch/qemu-user-static), to test containers on other hardware architecture via emulation
7546

7647
Before cloning the repository or working within it, set the [file mode creation mask](https://en.wikipedia.org/wiki/Umask) to `0022` or `u=rwx,g=rx,o=rx`.
7748

49+
## Coding Style
50+
51+
Follow [the Docker Official Images review guidelines](https://github.com/docker-library/official-images#review-guidelines) and [Dockerfile best practices](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/).
52+
53+
In Dockerfiles and shell scripts, please use tabs for indentation instead of spaces.
54+
55+
## Commit Messages
56+
57+
This project uses [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/). Valid commit types are:
58+
59+
- **build**—changes to the build system or external dependencies
60+
61+
- **ci**—changes to the CI configuration files and scripts
62+
63+
- **docs**—documentation-only changes
64+
65+
- **feat**—a new feature
66+
67+
- **fix**—a bug fix
68+
69+
- **perf**—a code change that improves performance
70+
71+
- **refactor**—a code change that neither fixes a bug nor adds a feature
72+
73+
- **test**—new tests or corrections to existing tests
74+
75+
No commit scopes are currently in use.
76+
7877
## Update Process
7978

80-
1. If necessary, update the list of version aliases at the beginning of `generate-stackbrew-library.sh`.
79+
In a fork of this repository:
80+
81+
1. Review the list of version aliases at the beginning of `generate-stackbrew-library.sh`.
82+
83+
2. Run [update.sh](update.sh), specifying the desired major and minor version of SATOSA. For example:
8184

82-
2. Update `versions.json` and the container image definitions by running `update.sh`. Specify the desired major and minor version of SATOSA. For example:
8385
```bash
8486
./update.sh 8.1
8587
```
8688

87-
3. If necessary, remove outdated versions of SATOSA or the base container images from `versions.json`. Delete the corresponding SATOSA container image definitions, e.g., `8.0/`, `8.1/*alpine3.14*/`.
89+
3. Remove outdated versions of SATOSA or base container images from `versions.json`, and delete the corresponding SATOSA container image definitions from the repository, e.g., the `8.0/` or `8.1/*alpine3.14*/` folders.
8890

89-
4. Commit all of the modified files. Mention the new SATOSA or base container version in the commit message subject. Reference the release announcement in the commit message body. For example:
90-
```
91-
feat: version bump to SATOSA v8.1.0
91+
4. Mention the new SATOSA or base container version in the commit message subject, reference the release announcement in the commit message body. For example:
9292

93-
Cf. https://github.com/IdentityPython/SATOSA/commit/d44b54433c5b817cf0409855881f6f2c80c27f5c
94-
```
95-
Or for example:
96-
```
97-
feat: version bump to Alpine Linux v3.16
93+
```
94+
feat: version bump to SATOSA v8.1.0
9895
99-
Cf. https://www.alpinelinux.org/posts/Alpine-3.16.0-released.html
100-
```
96+
Cf. https://github.com/IdentityPython/SATOSA/commit/d44b54433c5b817cf0409855881f6f2c80c27f5c
97+
```
10198
102-
5. GitHub Actions will run two workflows on push. [Verify Templating](../../actions/workflows/verify-templating.yml) checks for uncommitted changes. [GitHub CI](../../actions/workflows/ci.yml) builds and tests all of the container images.
99+
Or for example:
103100
104-
6. If both workflows complete successfully, generate a new [Docker Official Images](https://github.com/docker-library/official-images/) library entry by running the following command:
105-
```bash
106-
./generate-stackbrew-library.sh
107-
```
101+
```
102+
feat: version bump to Alpine Linux v3.16
103+
104+
Cf. https://www.alpinelinux.org/posts/Alpine-3.16.0-released.html
105+
```
106+
107+
5. Submit a pull request after both GitHub Actions workflows complete successfully.
108+
109+
After accepting a pull request, fork and edit [the Docker Official Images library entry for SATOSA](https://github.com/docker-library/official-images/edit/master/library/satosa):
110+
111+
1. Replace its contents with the output of [generate-stackbrew-library.sh](generate-stackbrew-library.sh).
112+
113+
2. Use a commit message referencing the release announcement. For example:
108114
109-
7. Fork and edit [the Docker Official Images library entry for SATOSA](https://github.com/docker-library/official-images/edit/master/library/satosa). Replace its contents with the output of `generate-stackbrew-library.sh`. Use a commit message referencing the release announcement. Submit a pull request when done. For example:
110115
```
111116
Update SATOSA to v8.0.1
112117

113118
Cf. https://github.com/IdentityPython/SATOSA/commit/1a408439a6b8855346e5ca2c645dee6ab1ce8c0a
114119
```
115-
Or for example:
120+
121+
Or for example:
122+
116123
```
117124
Update SATOSA base container images to Alpine Linux v3.16
118125

119126
Cf. https://www.alpinelinux.org/posts/Alpine-3.16.0-released.html
120127
```
128+
129+
3. Submit a pull request when finished.

0 commit comments

Comments
 (0)