Skip to content

Commit fb2747f

Browse files
detrodetro
committed
feat: updating Taskfile.yaml to support the new multi-module architecture
Also updated the `CONTRIBUTING.md` doc to reflect how to use the new `task`s and how the new release process is done.
1 parent 6a0bf2b commit fb2747f

2 files changed

Lines changed: 221 additions & 15 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 94 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,47 @@ $ task tools.update
4141
$ task tools.install
4242
```
4343

44+
### Go Workspaces Setup
45+
46+
This repository is structured as a multi-module Go Workspace to isolate the dependencies of each plugin module.
47+
48+
Since `go.work` and `go.work.sum` files are excluded from git, you need to create your workspace locally before you can build, lint, or run tests:
49+
50+
```shell
51+
# Initialize the workspace at the root directory
52+
$ go work init
53+
54+
# Add the root module and all plugins/examples to the workspace
55+
$ go work use . $(find plugin examples -name go.mod -exec dirname {} \;)
56+
```
57+
58+
This creates a local `go.work` file containing:
59+
```go
60+
go 1.26.3
61+
62+
use (
63+
.
64+
./plugin/modifier/jsonpath
65+
./plugin/modifier/tomlpath
66+
./plugin/modifier/yamlpath
67+
./plugin/modifier/xpath
68+
./plugin/source/1password
69+
./plugin/source/aws
70+
./plugin/source/azure
71+
./plugin/source/bitwarden
72+
./plugin/source/gcp
73+
./plugin/source/keeper
74+
./plugin/source/kubernetes
75+
./plugin/source/vault
76+
./examples/basic
77+
./examples/kong
78+
./examples/urfave-cli
79+
./examples/viper
80+
)
81+
```
82+
83+
Now, your IDE and standard Go tooling will seamlessly compile, lint, and run tests across all workspace packages!
84+
4485
### `task` toolchain
4586

4687
This codebase uses [task] to define a simple "development toolchain"
@@ -57,22 +98,42 @@ $ task <TAB><TAB>
5798
5899
### Running Tests
59100

60-
To run the full test suite (including integration tests):
101+
By default, the test tasks recursively run across the root module and **all** workspace submodules (plugins and examples) automatically:
102+
103+
To run the full test suite across the entire workspace (including integration tests):
61104
```shell
62105
$ task test
63106
```
64107

65-
To run only unit tests (skip integration tests):
108+
To run only unit tests across the entire workspace (skip integration tests):
66109
```shell
67110
$ task test.short
68111
```
69112

70-
You can optionally pass a specific package path to any test task by appending `-- <path>`. This is very useful when working on a specific plugin:
113+
#### Targeting Specific Packages/Plugins
114+
115+
If you are developing a specific plugin, you can avoid running the whole workspace test suite by targeting its directory path. Append `-- <path>` to target a single submodule directory:
71116
```shell
117+
# Run full tests on a single plugin module
72118
$ task test -- ./plugin/source/1password
119+
120+
# Run unit tests on a single plugin module
121+
$ task test.short -- ./plugin/source/1password
122+
123+
# Run tests on the root module's types directory
73124
$ task test.short -- ./types
74125
```
75126

127+
### Dependency Management
128+
129+
The dependency task is also workspace-aware. You can update and tidy the `go.mod` files of the root module, all 12 plugins, and all examples with a single command:
130+
131+
```shell
132+
$ task dependencies.update
133+
```
134+
135+
This runs `go get -t -u ./...` and `go mod tidy` in the root and in every submodule folder sequentially.
136+
76137
### Update tools
77138

78139
```shell
@@ -85,7 +146,36 @@ $ asdf install
85146

86147
## Pull Request Process
87148

88-
TODO
149+
We follow a standard GitHub PR flow:
150+
151+
1. Fork the repository and create your branch from `main`.
152+
2. Ensure that any code changes are covered by tests.
153+
3. Make sure all tests pass locally via `task test` or `task test.short`.
154+
4. Ensure your changes pass the linter via `task lint`.
155+
5. Submit your PR and write a descriptive summary.
156+
157+
## Release Process
158+
159+
Because this repository utilizes a Go Workspace with independent submodules, releasing a new version requires tagging **both** the root module and the submodule paths.
160+
161+
When releasing version `vX.Y.Z`:
162+
163+
1. Update the `CHANGELOG.md` file following the [Keep a Changelog](https://keepachangelog.com/) guidelines.
164+
2. Push your changes to `main`.
165+
3. Use the unified `task tag` utility to automatically tag either the whole workspace or a specific submodule:
166+
```shell
167+
# Tag the entire workspace (root module and all 16 submodules/examples) at v2.0.0:
168+
$ task tag -- v2.0.0
169+
170+
# Tag ONLY a specific submodule (e.g., if releasing a standalone patch for a plugin):
171+
$ task tag -- v2.0.1 plugin/source/aws
172+
```
173+
4. Push all generated tags to GitHub:
174+
```shell
175+
$ git push origin --tags
176+
```
177+
178+
By using prefix-based tags (e.g., `plugin/source/aws/vX.Y.Z`), Go clients can cleanly import specific submodules at defined releases independent of each other.
89179

90180
## Code of Conduct
91181

‎Taskfile.yaml‎

Lines changed: 127 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -6,51 +6,167 @@ env:
66

77
tasks:
88
generate:
9-
cmd: go generate ./...
9+
cmd: |
10+
go generate ./...
11+
find plugin examples -name go.mod -exec dirname {} \; | while read -r dir; do
12+
echo "Generating code in $dir..."
13+
(cd "$dir" && go generate ./...)
14+
done
1015
1116
build:
1217
deps: [generate]
13-
cmd: go build .
18+
cmd: |
19+
go build .
20+
find plugin examples -name go.mod -exec dirname {} \; | while read -r dir; do
21+
echo "Building in $dir..."
22+
(cd "$dir" && go build ./...)
23+
done
1424
1525
test:
1626
deps: [test.full]
1727

1828
test.short:
19-
cmd: go test -v -race -cover -short {{.CLI_ARGS | default "./..."}}
29+
cmd: |
30+
{{if .CLI_ARGS}}
31+
go test -v -race -cover -short {{.CLI_ARGS}}
32+
{{else}}
33+
go test -v -race -cover -short ./...
34+
find plugin examples -name go.mod -exec dirname {} \; | while read -r dir; do
35+
echo "Testing $dir..."
36+
(cd "$dir" && go test -v -race -cover -short ./...)
37+
done
38+
{{end}}
2039
2140
test.full:
22-
cmd: go test -v -race -cover {{.CLI_ARGS | default "./..."}}
41+
cmd: |
42+
{{if .CLI_ARGS}}
43+
go test -v -race -cover {{.CLI_ARGS}}
44+
{{else}}
45+
go test -v -race -cover ./...
46+
find plugin examples -name go.mod -exec dirname {} \; | while read -r dir; do
47+
echo "Testing $dir..."
48+
(cd "$dir" && go test -v -race -cover ./...)
49+
done
50+
{{end}}
2351
2452
test.ci:
25-
cmd: go test -v -race -coverprofile=coverage.out -covermode=atomic {{.CLI_ARGS | default "./..."}}
53+
cmd: |
54+
{{if .CLI_ARGS}}
55+
go test -v -race -coverprofile=coverage.out -covermode=atomic {{.CLI_ARGS}}
56+
{{else}}
57+
go test -v -race -coverprofile=coverage.out -covermode=atomic ./...
58+
find plugin examples -name go.mod -exec dirname {} \; | while read -r dir; do
59+
echo "Testing $dir..."
60+
(cd "$dir" && go test -v -race -coverprofile=coverage.out -covermode=atomic ./...)
61+
done
62+
{{end}}
2663
2764
lint:
28-
cmd: golangci-lint run --allow-parallel-runners --verbose
65+
cmd: |
66+
golangci-lint run --allow-parallel-runners --verbose
67+
find plugin examples -name go.mod -exec dirname {} \; | while read -r dir; do
68+
echo "Linting in $dir..."
69+
(cd "$dir" && golangci-lint run --allow-parallel-runners --verbose)
70+
done
2971
3072
vuln:
3173
desc: Run govulncheck for vulnerability scanning
32-
cmd: govulncheck ./...
74+
cmd: |
75+
govulncheck ./...
76+
find plugin examples -name go.mod -exec dirname {} \; | while read -r dir; do
77+
echo "Scanning vulnerabilities in $dir..."
78+
(cd "$dir" && govulncheck ./...)
79+
done
3380
3481
lint-fix:
35-
cmd: golangci-lint run --fix --allow-parallel-runners --verbose
82+
cmd: |
83+
golangci-lint run --fix --allow-parallel-runners --verbose
84+
find plugin examples -name go.mod -exec dirname {} \; | while read -r dir; do
85+
echo "Fixing linter issues in $dir..."
86+
(cd "$dir" && golangci-lint run --fix --allow-parallel-runners --verbose)
87+
done
3688
3789
fmt:
38-
cmd: golangci-lint fmt -v
90+
cmd: |
91+
golangci-lint fmt -v
92+
find plugin examples -name go.mod -exec dirname {} \; | while read -r dir; do
93+
echo "Formatting in $dir..."
94+
(cd "$dir" && golangci-lint fmt -v)
95+
done
3996
4097
run:
4198
cmd: go run . {{.CLI_ARGS}}
4299

43100
mod.update:
44-
cmd: go get -t -u ./...
101+
cmd: |
102+
echo "Updating root module..."
103+
go get -t -u ./...
104+
105+
find plugin examples -name go.mod -exec dirname {} \; | while read -r dir; do
106+
echo "Updating dependencies in $dir..."
107+
(cd "$dir" && go get -t -u ./...)
108+
done
45109
46110
mod.tidy:
47-
cmd: go mod tidy -v
111+
cmd: |
112+
echo "Tidying root module..."
113+
go mod tidy -v
114+
115+
find plugin examples -name go.mod -exec dirname {} \; | while read -r dir; do
116+
echo "Tidying module in $dir..."
117+
(cd "$dir" && go mod tidy -v)
118+
done
48119
49120
dependencies.update:
50121
deps:
51122
- mod.update
52123
- mod.tidy
53124

125+
tag:
126+
desc: Create release tags for the root module and submodules
127+
cmd: |
128+
# Check if version was provided
129+
if [ -z "{{.CLI_ARGS}}" ]; then
130+
echo "Error: You must provide a version tag (e.g. task tag -- v2.0.0)"
131+
exit 1
132+
fi
133+
134+
# Parse arguments
135+
set -- {{.CLI_ARGS}}
136+
TAG_VER="$1"
137+
SUBMOD_PATH="$2"
138+
139+
# Validate version starts with 'v'
140+
if [[ ! "$TAG_VER" =~ ^v[0-9] ]]; then
141+
echo "Error: Version must start with 'v' followed by a number (e.g. v2.0.0), got '$TAG_VER'"
142+
exit 1
143+
fi
144+
145+
if [ -n "$SUBMOD_PATH" ]; then
146+
# Trim leading/trailing slashes from path
147+
SUBMOD_PATH="${SUBMOD_PATH#/}"
148+
SUBMOD_PATH="${SUBMOD_PATH%/}"
149+
150+
# Verify that sub-module exists and contains a go.mod
151+
if [ ! -f "$SUBMOD_PATH/go.mod" ]; then
152+
echo "Error: Submodule directory '$SUBMOD_PATH' does not exist or does not contain a go.mod file"
153+
exit 1
154+
fi
155+
156+
echo "Tagging submodule '$SUBMOD_PATH' with tag: $SUBMOD_PATH/$TAG_VER"
157+
git tag "$SUBMOD_PATH/$TAG_VER"
158+
else
159+
echo "Tagging root module with tag: $TAG_VER"
160+
git tag "$TAG_VER"
161+
162+
find plugin examples -name go.mod -exec dirname {} \; | while read -r dir; do
163+
echo "Tagging submodule '$dir' with tag: $dir/$TAG_VER"
164+
git tag "$dir/$TAG_VER"
165+
done
166+
fi
167+
168+
echo "Tags created successfully. To push tags, run: git push origin --tags"
169+
54170
tools.plugins:
55171
desc: Install all necessary asdf plugins
56172
cmd: |

0 commit comments

Comments
 (0)