Skip to content

Commit ce9f1e9

Browse files
JoibelJoibel
committed
feat: new-features automated documentation
Signed-off-by: Alan Clucas <alan@clucas.org>
1 parent 48f877c commit ce9f1e9

File tree

14 files changed

+1311
-3
lines changed

14 files changed

+1311
-3
lines changed

‎.features/TEMPLATE.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
<!-- Required: All of these fields are required, including at least one issue -->
2+
Description: <!-- A brief one line description of the feature -->
3+
Author: <!-- Author name and GitHub link in markdown format e.g. [Alan Clucas](https://github.com/Joibel) -->
4+
Component: <!-- component name here, see hack/featuregen/components.go for the list -->
5+
Issues: <!-- Space separated list of issues 1234 5678 -->
6+
7+
<!--
8+
Optional
9+
Additional details about the feature written in markdown, aimed at users who want to learn about it
10+
* Explain when you would want to use the feature
11+
* Include code examples if applicable
12+
* Provide working examples
13+
* Format code using back-ticks
14+
* Use Kubernetes style
15+
* One sentence per line of markdown
16+
-->

‎.features/pending/feat-notes.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Component: Build and Development
2+
Issues: 14155
3+
Description: Document features as they are created
4+
Author: [Alan Clucas](https://github.com/Joibel)
5+
6+
To assist with creating release documentation and blog postings, all features now require a document in .features/pending explaining what they do for users.

‎.github/workflows/ci-build.yaml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,7 @@ jobs:
8484
- .clang-format
8585
lint:
8686
- *tests
87+
- .features/**
8788
# plus lint config
8889
- .golangci.yml
8990
# all GH workflows / actions
@@ -99,6 +100,7 @@ jobs:
99100
# docs scripts & tools from `make docs`
100101
- hack/docs/copy-readme.sh
101102
- hack/docs/check-env-doc.sh
103+
- hack/featuregen/**
102104
- .markdownlint.yaml
103105
- .mlc_config.json
104106
- .spelling

‎.github/workflows/pr.yaml

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,8 +14,55 @@ permissions:
1414
jobs:
1515
title-check:
1616
runs-on: ubuntu-24.04
17+
outputs:
18+
type: ${{ steps.semantic-pr-check.outputs.type }}
1719
steps:
1820
- name: Check PR Title's semantic conformance
21+
id: semantic-pr-check
1922
uses: amannn/action-semantic-pull-request@0723387faaf9b38adef4775cd42cfd5155ed6017 # v5.5.3
2023
env:
2124
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
25+
26+
feature-pr-handling:
27+
needs: title-check
28+
runs-on: ubuntu-24.04
29+
if: needs.title-check.outputs.type == 'feat'
30+
env:
31+
PR_HEAD: ${{ github.event.pull_request.head.sha }}
32+
steps:
33+
- uses: actions/setup-go@0c52d547c9bc32b1aa3301fd7a9cb496313a4491 # v5.0.0
34+
with:
35+
go-version: "1.24"
36+
cache: true
37+
- name: Checkout
38+
uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
39+
with:
40+
fetch-depth: 0
41+
42+
- name: Ensure ./.features/*.md addition(s)
43+
run: |
44+
if [[ 1 -gt $(git diff --diff-filter=A --name-only $(git merge-base origin/${{ github.base_ref }} $PR_HEAD) $PR_HEAD ./.features | grep -c \\.md) ]]
45+
then
46+
echo "No feature description was added to the ./.features/ directory for this feature PR."
47+
echo "Please add a .md file to the ./.features/ directory."
48+
echo "See docs/running-locally.md for more details."
49+
false
50+
else
51+
echo "A feature description was added to the ./.features/ directory."
52+
fi
53+
54+
- name: Validate ./.features/*.md changes
55+
run: |
56+
make features-validate \
57+
|| { echo "New ./.features/*.md file failed validation."; exit 1; }
58+
59+
# In order to validate any links in the yaml file, render the config to markdown
60+
- name: Render .features/*.md feature descriptions
61+
run: make features-preview > features_preview.md
62+
63+
- name: Link Checker
64+
id: lychee
65+
uses: lycheeverse/lychee-action@f613c4a64e50d792e0b31ec34bbcbba12263c6a6 # f613c4a64e50d792e0b31ec34bbcbba12263c6a6
66+
with:
67+
args: "--verbose --no-progress ./features_preview.md"
68+
failIfEmpty: false

‎.gitignore

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ dist/
88
# delve debug binaries
99
cmd/**/debug
1010
hack/**/debug
11+
hack/featuregen/featuregen
1112
/argo
1213
/argoexec
1314
release-notes
@@ -46,6 +47,6 @@ sdks/python/client/dist/*
4647
manifests/install.yaml
4748
manifests/namespace-install.yaml
4849
/logs
49-
node_modules
50+
node_modules
5051
result
5152
.devenv

‎.spelling

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -261,7 +261,11 @@ v3.4.
261261
v3.4.4
262262
v3.5
263263
v3.6
264+
v3.6.0
265+
v3.6.1
266+
v3.6.5
264267
v3.7
268+
v3.7.0
265269
validator
266270
vendored
267271
versioned

‎Makefile

Lines changed: 39 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -477,8 +477,9 @@ manifests-validate:
477477
$(TOOL_GOLANGCI_LINT): Makefile
478478
curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b `go env GOPATH`/bin v2.1.1
479479

480-
.PHONY: lint
481-
lint: ui/dist/app/index.html $(TOOL_GOLANGCI_LINT)
480+
.PHONY: lint lint-go lint-ui
481+
lint: lint-go lint-ui features-validate
482+
lint-go: $(TOOL_GOLANGCI_LINT) ui/dist/app/index.html
482483
rm -Rf v3 vendor
483484
# If you're using `woc.wf.Spec` or `woc.execWf.Status` your code probably won't work with WorkflowTemplate.
484485
# * Change `woc.wf.Spec` to `woc.execWf.Spec`.
@@ -488,6 +489,8 @@ lint: ui/dist/app/index.html $(TOOL_GOLANGCI_LINT)
488489
go mod tidy
489490
# Lint Go files
490491
$(TOOL_GOLANGCI_LINT) run --fix --verbose
492+
493+
lint-ui: ui/dist/app/index.html
491494
# Lint the UI
492495
if [ -e ui/node_modules ]; then yarn --cwd ui lint ; fi
493496
# Deduplicate Node modules
@@ -819,3 +822,37 @@ release-notes: /dev/null
819822
.PHONY: checksums
820823
checksums:
821824
sha256sum ./dist/argo-*.gz | awk -F './dist/' '{print $$1 $$2}' > ./dist/argo-workflows-cli-checksums.txt
825+
826+
FEATURE_FILENAME?=$(shell git branch --show-current)
827+
.PHONY: feature-new
828+
feature-new: hack/featuregen/featuregen
829+
# Create a new feature documentation file in .features/pending/ ready for editing
830+
# Uses the current branch name as the filename by default, or specify with FEATURE_FILENAME=name
831+
$< new --filename $(FEATURE_FILENAME)
832+
833+
.PHONY: features-validate
834+
features-validate: hack/featuregen/featuregen
835+
# Validate all pending feature documentation files
836+
$< validate
837+
838+
.PHONY: features-preview
839+
features-preview: hack/featuregen/featuregen
840+
# Preview how the features will appear in the documentation (dry run)
841+
# Output to stdout
842+
$< update --dry
843+
844+
.PHONY: features-update
845+
features-update: hack/featuregen/featuregen
846+
# Update the features documentation, but keep the feature files in the pending directory
847+
# Updates docs/new-features.md for release-candidates
848+
$< update --version $(VERSION)
849+
850+
.PHONY: features-release
851+
features-release: hack/featuregen/featuregen
852+
# Update the features documentation AND move the feature files to the released directory
853+
# Use this for the final update when releasing a version
854+
$< update --version $(VERSION) --final
855+
856+
hack/featuregen/featuregen: hack/featuregen/main.go hack/featuregen/contents.go hack/featuregen/contents_test.go hack/featuregen/main_test.go
857+
go test ./hack/featuregen
858+
go build -o $@ ./hack/featuregen

‎docs/releasing.md

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,37 @@ git tag v3.3.4
5050
git push upstream v3.3.4 # or origin if you do not use upstream
5151
```
5252

53+
### Feature Releases
54+
55+
For feature releases (e.g., v3.6.0, v3.7.0) and not patch releases (e.g., v3.6.1, v3.6.5), you need to update the feature descriptions with the new version.
56+
57+
For release candidates, use:
58+
59+
```bash
60+
make features-update VERSION=v3.6.0
61+
git add docs/new-features.md
62+
git commit -m "chore: Update feature descriptions for v3.6.0"
63+
git push
64+
```
65+
66+
This will update all pending feature descriptions with the current version and include them in the upcoming release notes.
67+
The features will remain in the pending directory, allowing for further updates if needed.
68+
69+
For the final release, use:
70+
71+
```bash
72+
make features-release VERSION=v3.6.0
73+
git add .features
74+
git add docs/new-features.md
75+
git commit -m "chore: Release feature descriptions for v3.6.0"
76+
git push
77+
```
78+
79+
This will update the feature descriptions and move them from the pending directory to the released directory for the specific version.
80+
This is the final step that should be done when releasing a new version.
81+
82+
### Release Build
83+
5384
GitHub Actions will automatically build and publish your release. This takes about 1h. Set your self a reminder to check
5485
this was successful.
5586

‎docs/running-locally.md

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -289,6 +289,44 @@ git commit --signoff -m 'fix: Fixed broken thing. Fixes #1234'
289289
git commit --signoff -m 'feat: Added a new feature. Fixes #1234'
290290
```
291291

292+
### Creating Feature Descriptions
293+
294+
When adding a new feature, you must create a feature description file that will be used to generate new feature information when we do a feature release:
295+
296+
```bash
297+
make feature-new
298+
```
299+
300+
This will create a new feature description file in the `.features` directory which you must then edit to describe your feature.
301+
By default, it uses your current branch name as the file name.
302+
The name of the file doesn't get used by the tooling, it just needs to be unique to your feature so as not to collide on merge.
303+
You can also specify a custom file name:
304+
305+
```bash
306+
make feature-new FEATURE_FILENAME=my-awesome-feature
307+
```
308+
309+
You must have an issue number to associate with your PR for features, and that must be placed in this file.
310+
It seems reasonable that all new features are discussed in an issue before being developed.
311+
There is a `Component` field which must match one of the fields in `hack/featuregen/components.go`
312+
313+
The feature file should be included in your PR to document your changes.
314+
Before submitting, you can validate your feature file:
315+
316+
```bash
317+
make features-validate
318+
```
319+
320+
The `pre-commit` target will also do that.
321+
322+
You can also preview how your feature will appear in the release notes:
323+
324+
```bash
325+
make features-preview
326+
```
327+
328+
This command runs a dry-run of the release notes generation process, showing you how your feature will appear in the markdown file that will be used to generate the release notes.
329+
292330
## Troubleshooting
293331

294332
* When running `make pre-commit -B`, if you encounter errors like

‎hack/featuregen/components.go

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
package main
2+
3+
import (
4+
"strings"
5+
)
6+
7+
// Valid component names.
8+
// This is the order they will appear in the new feature file.
9+
// Try not to just add too many components, this is just for categorization in the feature docs.
10+
var validComponents = []string{
11+
"General",
12+
"UI",
13+
"CLI",
14+
"CronWorkflows",
15+
"Telemetry",
16+
"Build and Development",
17+
}
18+
19+
func isValidComponent(component string) bool {
20+
for _, c := range validComponents {
21+
if c == component {
22+
return true
23+
}
24+
}
25+
return false
26+
}
27+
28+
func listValidComponents() string {
29+
return strings.Join(validComponents, ", ")
30+
}

0 commit comments

Comments
 (0)