Bootstrap: Default Workflow scaffold
Repo created for a reference/review of the iTelescope.net remote telescope network. This commit copies the Default Workflow in (CLAUDE.md and docs/ from the Default-Workflow repo), adds a .gitignore (secrets and scratch), and fills in state/PROJECT.md with the objective: review every telescope on the network and provide a choosing guide, using only public sources (support article and the maintained Google Sheet; the go.itelescope.net launchpad is login-only).
This commit is contained in:
commit
3fad877dee
7 changed files with 350 additions and 0 deletions
76
docs/workflow.md
Normal file
76
docs/workflow.md
Normal file
|
|
@ -0,0 +1,76 @@
|
|||
# Workflow
|
||||
|
||||
The branch, commit, PR and merge process for every feature. A "feature" is any unit of
|
||||
change: a new capability, a fix, a refactor.
|
||||
|
||||
## 1. Branch per feature
|
||||
|
||||
Never build directly on the trunk. Start each feature from an up to date trunk:
|
||||
|
||||
```
|
||||
git checkout main
|
||||
git pull
|
||||
git checkout -b feature/<short-kebab-description>
|
||||
```
|
||||
|
||||
Use a clear prefix: `feature/`, `fix/`, `refactor/`, `docs/`.
|
||||
|
||||
## 2. Commit with full notes
|
||||
|
||||
Commit in logical steps, not one giant dump at the end. Every commit message carries
|
||||
the full record of what changed and why, because the commit history is the primary
|
||||
source a later documentation session reads.
|
||||
|
||||
Message shape:
|
||||
|
||||
```
|
||||
<type>: <concise summary in the imperative>
|
||||
|
||||
What changed:
|
||||
- <file or area>: <what and why>
|
||||
- ...
|
||||
|
||||
Why:
|
||||
- <the reasoning, constraints, or decision behind the change>
|
||||
|
||||
Notes:
|
||||
- <anything a cold session should know: trade-offs, follow-ups, gotchas>
|
||||
```
|
||||
|
||||
Do not write "written by Claude" in code or messages. If the project convention
|
||||
requires an authorship tag (for example `ai:claude`), follow that project's rule.
|
||||
|
||||
## 3. Keep state files current
|
||||
|
||||
As you work, update `state/TODO.md` and `state/DECISIONS.md`. Decisions go in the log
|
||||
with a date and rationale. This is what lets the next session skip the chat history.
|
||||
|
||||
## 4. Open a PR when the feature is complete
|
||||
|
||||
When the feature is done and self consistent, push the branch and open a PR. The PR
|
||||
description is the human and machine readable summary of the feature. Use the template
|
||||
in `templates/PR_TEMPLATE.md`. It must state:
|
||||
|
||||
- **Feature** - what was built, in plain terms.
|
||||
- **What was achieved** - the outcome, and how to verify it.
|
||||
- **Tools used** - languages, libraries, commands, services involved.
|
||||
- **How it works** - enough for a documentation session to start from the PR alone.
|
||||
- **Follow ups** - anything deferred.
|
||||
|
||||
## 5. Merge into the trunk
|
||||
|
||||
Merge the PR into the trunk once it is complete. Prefer a merge that preserves the
|
||||
commit history (the notes in each commit are valuable). Delete the feature branch after
|
||||
merge.
|
||||
|
||||
## 6. Do not document in this session
|
||||
|
||||
Writing the user facing documentation is a separate job, done in a separate session,
|
||||
against the merged history. See [Documentation policy](documentation-policy.md). Your
|
||||
job in the building session ends at a merged, well commented, well described feature.
|
||||
|
||||
## Summary
|
||||
|
||||
```
|
||||
branch -> commit (full notes) -> update state/ -> PR (feature, tools, outcome) -> merge -> stop
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue