Skip to content

Commit 67b17f1

Browse files
SahulKolaSahulKola
authored
Merge pull request #13 from SahulKola/docs/add-detailed-docs
docs: update detailed internal documentation on whole project and workflow
2 parents 2dd3259 + ffe7ae4 commit 67b17f1

5 files changed

Lines changed: 1111 additions & 0 deletions

File tree

‎handbook/RELEASE_GUIDE.md‎

Lines changed: 226 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,226 @@
1+
# Release Guide
2+
3+
A step-by-step reference for shipping a versioned release of git-devkit. Covers the CLI package, the docs-app, and the GitHub release tag. Follow this every time you want to publish something to users.
4+
5+
---
6+
7+
## Overview of what a release includes
8+
9+
git-devkit has three distinct "artifacts" that can be released independently or together:
10+
11+
| Artifact | What it is | Where it lives |
12+
|---|---|---|
13+
| CLI package | The `git-multi-ssh` Node.js tool | Published to npm, bundled from `bin/` |
14+
| Docs app | The Angular documentation site | Deployed as static output to GitHub Pages |
15+
| Git tag + GitHub Release | The version marker on the repo | GitHub Releases page |
16+
17+
In most cases you will release all three at once.
18+
19+
---
20+
21+
## Pre-release checklist
22+
23+
Before you increment any version number, confirm the following:
24+
25+
- [ ] All changes on `main` are committed and pushed
26+
- [ ] `git status` shows a clean working tree
27+
- [ ] CI / local tests pass (`pnpm test` inside `docs-app/`)
28+
- [ ] The docs-app builds without errors (`pnpm run build:prod` inside `docs-app/`)
29+
- [ ] The CLI builds without errors (`npm run build` from repo root)
30+
- [ ] Any new features are documented in the relevant handbook files
31+
- [ ] `CHANGELOG.md` has an entry describing what changed
32+
33+
---
34+
35+
## Step 1: Decide the version bump
36+
37+
git-devkit follows [Semantic Versioning](https://semver.org): `MAJOR.MINOR.PATCH`
38+
39+
| Change type | Which number to bump | Example |
40+
|---|---|---|
41+
| Breaking change (removes/renames functionality) | MAJOR | `0.1.0` → `1.0.0` |
42+
| New feature that is backward compatible | MINOR | `0.1.0` → `0.2.0` |
43+
| Bug fix or small internal change | PATCH | `0.1.0` → `0.1.1` |
44+
45+
The current version is in `package.json` at the repo root.
46+
47+
---
48+
49+
## Step 2: Create a release branch
50+
51+
```bash
52+
# Start from an up-to-date main
53+
git checkout main && git pull
54+
55+
# Create a release branch
56+
git checkout -b release/v0.2.0
57+
```
58+
59+
Working on a release branch lets you prepare the version bump separately from feature work.
60+
61+
---
62+
63+
## Step 3: Bump the version
64+
65+
Edit `package.json` at the repo root and update the `"version"` field:
66+
67+
```json
68+
{
69+
"version": "0.2.0"
70+
}
71+
```
72+
73+
Then run the CLI build to make sure it still compiles:
74+
75+
```bash
76+
npm run build
77+
```
78+
79+
This runs `scripts/build.mjs` which bundles `bin/index.js` with esbuild into `dist/` and copies the updated `package.json` into `dist/`.
80+
81+
---
82+
83+
## Step 4: Update CHANGELOG
84+
85+
Open `handbook/technical/CHANGELOG.md` and add an entry at the top:
86+
87+
```
88+
## [0.2.0] - 2026-05-06
89+
90+
### Added
91+
- Multi-SSH daily use-cases page in docs-app
92+
93+
### Fixed
94+
- Windows installation guide now correctly recommends native setup script
95+
96+
### Changed
97+
- Removed npm CLI option from installation docs (source-only distribution)
98+
```
99+
100+
Keep the format consistent: Added / Fixed / Changed / Removed.
101+
102+
---
103+
104+
## Step 5: Build the docs-app
105+
106+
```bash
107+
cd docs-app
108+
pnpm run build:ghpages
109+
```
110+
111+
The `build:ghpages` script sets `--base-href /git-devkit/` so all asset paths are correct for GitHub Pages hosting.
112+
113+
The static output lands in `docs-app/dist/docs-app/browser/`.
114+
115+
---
116+
117+
## Step 6: Commit the version bump
118+
119+
```bash
120+
git add package.json handbook/technical/CHANGELOG.md
121+
git commit -m "chore(release): bump version to 0.2.0"
122+
```
123+
124+
---
125+
126+
## Step 7: Merge release branch to main
127+
128+
```bash
129+
git checkout main
130+
git merge release/v0.2.0 --no-ff
131+
git push origin main
132+
```
133+
134+
The `--no-ff` flag keeps a merge commit so the release point is visible in the history graph.
135+
136+
---
137+
138+
## Step 8: Tag the release
139+
140+
```bash
141+
git tag -a v0.2.0 -m "Release v0.2.0"
142+
git push origin v0.2.0
143+
```
144+
145+
The annotated tag (`-a`) stores a message alongside the tag, which GitHub uses as the default release notes title.
146+
147+
---
148+
149+
## Step 9: Publish to GitHub Releases
150+
151+
1. Go to `https://github.com/sahulkola/git-devkit/releases/new`
152+
2. Select the tag `v0.2.0` you just pushed
153+
3. Title: `v0.2.0 – <short description>`
154+
4. Body: paste the CHANGELOG entry for this version
155+
5. Click **Publish release**
156+
157+
---
158+
159+
## Step 10: Deploy docs-app to GitHub Pages
160+
161+
If you use the `gh-pages` branch strategy (most common for GitHub Pages):
162+
163+
```bash
164+
# From repo root
165+
cd docs-app
166+
npx gh-pages -d dist/docs-app/browser
167+
```
168+
169+
If your repository is configured to deploy from the `gh-pages` branch, GitHub Pages will pick up the new files automatically within a few minutes.
170+
171+
---
172+
173+
## Step 11: Delete the release branch
174+
175+
```bash
176+
git branch -d release/v0.2.0
177+
git push origin --delete release/v0.2.0
178+
```
179+
180+
---
181+
182+
## Post-release sanity check
183+
184+
- [ ] Visit `https://sahulkola.github.io/git-devkit/` and confirm the new page/content is live
185+
- [ ] The GitHub Releases page shows the new tag and notes
186+
- [ ] The version in `package.json` on `main` matches the tag
187+
188+
---
189+
190+
## Hotfix releases
191+
192+
If a critical bug surfaces after a release:
193+
194+
```bash
195+
git checkout main
196+
git checkout -b hotfix/v0.2.1
197+
198+
# fix the bug
199+
# bump patch version in package.json
200+
# add CHANGELOG entry
201+
202+
git commit -m "fix: <description>"
203+
git checkout main && git merge hotfix/v0.2.1 --no-ff
204+
git tag -a v0.2.1 -m "Hotfix v0.2.1"
205+
git push origin main --tags
206+
```
207+
208+
Then follow steps 9–11 above.
209+
210+
---
211+
212+
## Quick reference: CLI commands summary
213+
214+
```bash
215+
# Verify CLI builds
216+
npm run build # from repo root
217+
218+
# Verify docs-app builds
219+
cd docs-app && pnpm run build:prod
220+
221+
# Create and push tag
222+
git tag -a vX.Y.Z -m "Release vX.Y.Z" && git push origin vX.Y.Z
223+
224+
# Deploy docs to GitHub Pages
225+
cd docs-app && npx gh-pages -d dist/docs-app/browser
226+
```

‎handbook/RELEASE_ROAD.md‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
# Release Roadmap
2+
3+
Principles, philosophy, and future milestones that guide how git-devkit evolves and ships. This is not a rigid sprint plan; it is a set of values and intentions that keep releases aligned with the project's purpose.
4+
5+
---
6+
7+
## Core release principles
8+
9+
### 1. Ship working things, not complete things
10+
11+
A release is better when it solves one real problem reliably than when it attempts to solve ten problems partially. Each version should leave users strictly better off than before it.
12+
13+
### 2. Source-first distribution
14+
15+
git-devkit is distributed via Git clone and native setup scripts, not npm. This keeps the tool close to its audience (developers who use Git daily) and avoids a dependency chain that obscures what the tool actually does. Releases are marked by Git tags, not registry publishes.
16+
17+
### 3. Every release starts from a clean main
18+
19+
No feature work lands directly on `main`. All changes go through a branch, get reviewed, and merge when they are complete. This makes every point on `main` a valid release candidate.
20+
21+
### 4. The docs-app ships alongside the tool
22+
23+
Documentation is part of the product. When a feature is added to the CLI, the relevant docs-app page is updated in the same release. Releasing code without documentation is a half-release.
24+
25+
### 5. Semantic versioning communicates intent
26+
27+
Version numbers carry meaning. A PATCH does not introduce features. A MINOR does not break existing setups. A MAJOR signals that users need to take action. Bumping a number arbitrarily breaks this contract.
28+
29+
### 6. Breaking changes are opt-in
30+
31+
When a change would require users to re-run setup, edit their SSH config, or change how they clone repositories, it is a breaking change regardless of how small the code diff is. These changes always bump MAJOR and are documented prominently.
32+
33+
---
34+
35+
## Current release state
36+
37+
| Component | Version | Status |
38+
|---|---|---|
39+
| CLI (git-multi-ssh) | 0.0.2 | Stable - first functional release |
40+
| Docs-app | 0.0.0 | Active development |
41+
| GitHub release tag | None yet | Pending v0.1.0 tag |
42+
43+
---
44+
45+
## Planned milestones
46+
47+
### v0.1.0 — First tagged release
48+
49+
**Goal:** Stabilize existing functionality and make the project discoverable via a proper GitHub release.
50+
51+
- [ ] Tag `v0.1.0` on `main`
52+
- [ ] Publish GitHub Release with release notes
53+
- [ ] Deploy docs-app to GitHub Pages
54+
- [ ] Confirm installation scripts point to correct repo URLs
55+
- [ ] Verify setup on macOS, Windows (PowerShell), and Linux
56+
57+
---
58+
59+
### v0.2.0 — Documentation and discovery
60+
61+
**Goal:** The docs-app is the primary entry point for new users. Everything a user needs to get up and running should be reachable in two clicks.
62+
63+
- [ ] Installation page polished and OS-aware
64+
- [ ] Multi-SSH daily use-cases page live
65+
- [ ] Git aliases page with full reference
66+
- [ ] Stories page explaining real-world scenarios
67+
68+
---
69+
70+
### v0.3.0 — Developer experience improvements
71+
72+
**Goal:** Contributors and advanced users can extend or modify the tool easily.
73+
74+
- [ ] `handbook/how/` guides explain every internal module
75+
- [ ] Release process is documented and followed
76+
- [ ] Local development setup is documented (`docs-app` dev server instructions)
77+
- [ ] Test coverage for core library functions (`lib/`)
78+
79+
---
80+
81+
### v1.0.0 — Production-ready signal
82+
83+
**Goal:** The tool works reliably on all three platforms, the docs are complete, and the project is safe to recommend to other developers.
84+
85+
Criteria for v1.0.0:
86+
- Setup scripts tested on macOS, Windows PowerShell, Windows CMD, and Ubuntu
87+
- `git-multi-ssh` CLI handles edge cases (re-run on existing setup, partial config, SSH key already exists)
88+
- Docs-app covers all pages with accurate and tested commands
89+
- No open critical bugs
90+
91+
---
92+
93+
## What this project will not do
94+
95+
These are deliberate scope boundaries. Staying inside them keeps the tool focused.
96+
97+
- Will not become a general Git GUI or replace existing Git clients
98+
- Will not manage SSH keys automatically without user confirmation
99+
- Will not require a paid service, account, or subscription
100+
- Will not collect telemetry or usage data
101+
102+
---
103+
104+
## Contributing to the roadmap
105+
106+
If you are working on git-devkit and want to add a milestone, add it to the appropriate version section above. Use the same format: a goal statement and a checklist of specific deliverables. Keep milestones small enough to complete in a single release cycle.

0 commit comments

Comments
 (0)