Skip to content

Commit 6c5a2ba

Browse files
committed
docs(contributing): add release process, commit conventions, reporting
Expands CONTRIBUTING.md with the gaps surfaced by the v1.0.1 incident: - Release process section codifying the mandatory pre-tag smoke test (make app && open build/CloudTunnels.app), so a broken bundle never ships again. Documents the tag-driven workflow, SemVer policy, and the "cut a patch, do not retag" rule. - Conventional Commits table for commit and PR titles. - Bug-reporting checklist (sw_vers, uname -m, version, log slice) and a private-disclosure note for security issues. - Code of Conduct link. - Clone URL corrected from a stale personal fork to FournineCS/.
1 parent 2cca950 commit 6c5a2ba

1 file changed

Lines changed: 63 additions & 2 deletions

File tree

CONTRIBUTING.md

Lines changed: 63 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
# Contributing to CloudTunnels
22

3+
Thanks for your interest in CloudTunnels! This document covers the day-to-day
4+
mechanics of contributing. By participating you agree to abide by the
5+
[Code of Conduct](CODE_OF_CONDUCT.md).
6+
37
## Prerequisites
48

59
- macOS 13+
@@ -9,7 +13,7 @@
913
## Getting started
1014

1115
```bash
12-
git clone https://github.com/sampathinturi/cloud-tunnels.git
16+
git clone https://github.com/FournineCS/cloud-tunnels.git
1317
cd cloud-tunnels
1418
make test # must pass before you open a PR
1519
```
@@ -19,7 +23,36 @@ make test # must pass before you open a PR
1923
1. Fork the repo and create a branch (`git checkout -b feat/my-feature`)
2024
2. Make your changes
2125
3. Run `make test` — all tests must pass
22-
4. Open a pull request against `main`
26+
4. For UI / bundle / resource changes, also run `make app && open build/CloudTunnels.app` and confirm the app actually launches (see [Release process](#release-process) for why this matters)
27+
5. Open a pull request against `main`
28+
29+
## Commit messages and PR titles
30+
31+
We follow Conventional Commits. The commit/PR title prefix drives changelog
32+
categorization and tooling:
33+
34+
| Prefix | Use for |
35+
|---|---|
36+
| `feat:` | User-visible new feature |
37+
| `fix:` | User-visible bug fix |
38+
| `refactor:` | Internal change with no behavior change |
39+
| `docs:` | Documentation only |
40+
| `test:` | Tests only |
41+
| `ci:` / `build:` | CI workflow or build-system changes |
42+
| `chore:` | Tooling, deps, housekeeping |
43+
44+
Examples:
45+
- `feat(ssh): support multiple -L forwards per tunnel`
46+
- `fix(branding): load PNGs via Bundle.main, not SwiftPM Bundle.module`
47+
- `ci(release): notarize per-arch zips before stapling`
48+
49+
Keep the subject line under 72 characters. Use the body for the *why* — the
50+
diff already shows the *what*.
51+
52+
## Reporting bugs / asking questions
53+
54+
- **Bugs and feature requests** — open an issue at <https://github.com/FournineCS/cloud-tunnels/issues>. Include macOS version (`sw_vers`), CPU arch (`uname -m`), CloudTunnels version (`About` menu or `ctun --version`), and the relevant slice of `log stream --predicate 'subsystem == "com.fourninecloud.cloud-tunnels"' --info`.
55+
- **Security issues** — please do *not* file a public issue. Email the maintainers privately first.
2356

2457
## Adding a new tunnel provider
2558

@@ -54,3 +87,31 @@ Ad-hoc signing (`SIGN_IDENTITY=-`) is the default and is fine for all changes th
5487
## Tests
5588

5689
`make test` runs the full XCTest suite (~365 tests). No real `kubectl`, `gcloud`, or `aws` invocations happen in tests. Use `swift test --filter <ClassName>` to run a single class.
90+
91+
Pure argv builders, config parsers, and reducer-style helpers are the primary
92+
unit-test targets — anything that shells out should be factored into a pure
93+
static function and tested without spawning a process.
94+
95+
## Release process
96+
97+
Releases are tag-driven. Pushing a tag matching `v*` triggers
98+
`.github/workflows/release.yml`, which builds universal + per-arch zips,
99+
signs with the FOURNINE Developer ID, notarizes via `notarytool`, staples,
100+
and publishes a GitHub Release with `SHA256SUMS.txt`.
101+
102+
Before tagging:
103+
104+
1. `make test` — full suite green
105+
2. `make app && open build/CloudTunnels.app`**confirm the app actually launches and the menu-bar icon appears.** A green build does not guarantee a working `.app`; SwiftPM resource bundles, code-signing entitlements, and TCC requirements only surface at launch. The v1.0.1 release shipped a fatal crash because this step was skipped.
106+
3. Update relevant docs (`README.md`, `CLAUDE.md`) if behavior changed.
107+
4. Tag: `git tag -a vX.Y.Z -m "Release vX.Y.Z" && git push public vX.Y.Z`
108+
5. Watch the run: `gh run watch <run-id> --repo FournineCS/cloud-tunnels --exit-status`
109+
110+
If a release ships with a runtime bug, do **not** retag the same version —
111+
cut a patch release (`vX.Y.(Z+1)`) so anyone who already downloaded the
112+
broken build can tell what they have.
113+
114+
Versioning is [SemVer](https://semver.org/):
115+
- `MAJOR` — incompatible config schema or CLI changes
116+
- `MINOR` — new provider, new tool, new user-visible feature
117+
- `PATCH` — bug fixes, doc updates, build-system fixes

0 commit comments

Comments
 (0)