Laurence
3fad877dee
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).
76 lines
2.4 KiB
Markdown
76 lines
2.4 KiB
Markdown
# 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
|
|
```
|