Tirsvad
9ae0cba306
Add the planning baseline for RepoFoundry (create-project.sh), which creates GitHub and Gitea repositories, a Gitea -> GitHub push mirror and a local project with the SQA-QC-Framework. - BC-001 Business Case and SA-001 Stakeholder Analysis (S01, S02, S03) - PP-001 Project Plan: three phases, 2026-10-05 to 2026-11-13 (proposed) - MIL-001 Foundation, MIL-002 Repositories and Mirror, MIL-003 Scaffold and Release, with 18 task rows - US-001, UC-001 "Create a new project" and SSD-001 - Registry: PO language en; PP, MIL, US, UC and SSD rows added Decisions recorded: origin uses HTTPS from GITEA_URL unless the SSH test on port 10022 passes; S01 and S02 are held by one person for now. Refs: no issues synced yet (sync-project.sh dry run only)
83 lines
3.9 KiB
Markdown
83 lines
3.9 KiB
Markdown
# Create a new project
|
|
|
|
## Metadata
|
|
| Key | Value |
|
|
| --- | --- |
|
|
| ID | UC-001 |
|
|
| CrossReference | [US-001], [SA-001] |
|
|
|
|
## Version History
|
|
| Date | Status | Author | Reviewer | Change | Commit |
|
|
| --- | --- | --- | --- | --- | --- |
|
|
| 2026-10-05 | Proposed | Jens Tirsvad Nielsen | S02 | Initial version | pending |
|
|
|
|
---
|
|
|
|
**Format:** Fully Dressed
|
|
|
|
## Fully Dressed
|
|
|
|
- **Scope:** RepoFoundry (`create-project.sh`)
|
|
- **Level:** user-goal
|
|
- **Primary Actor:** Maintainer (S01 or S02; one person holds both roles for now)
|
|
- **Stakeholders and Interests:**
|
|
- S01 — new projects start from one repeatable, correct setup
|
|
- S02 — credentials are never exposed and nothing is overwritten silently
|
|
- S03 — the published procedure is documented and reusable
|
|
- **Preconditions:**
|
|
- `config.env` and `.env` exist and are valid.
|
|
- `git` and `curl` are installed.
|
|
- The Maintainer has a GitHub PAT, a Gitea token and SSH access to Gitea on port 10022.
|
|
- **Postconditions (success guarantee):**
|
|
- An empty repository exists on GitHub and on Gitea under the chosen owners.
|
|
- The Gitea repository is a push mirror to GitHub.
|
|
- A local project directory exists with credential-free remotes `origin` (Gitea) and `github`, the `framework` submodule, installed skills and hooks, and the copied templates.
|
|
- The Maintainer has a summary of what was created.
|
|
|
|
### Main Success Scenario
|
|
|
|
1. The Maintainer starts the project creation.
|
|
2. The system loads and validates the configuration and credentials and checks that the required tools exist.
|
|
3. The Maintainer provides the repository name, description, visibility, the GitHub owner, the Gitea owner, the local directory, and whether to enable the plan gate.
|
|
4. The system checks that both tokens work, that the owners accept new repositories, that the name is free on both hosts, and whether SSH to Gitea works.
|
|
5. The system creates the empty GitHub repository.
|
|
6. The system creates the empty Gitea repository.
|
|
7. The system configures the Gitea repository as a push mirror to GitHub and verifies it.
|
|
8. The system creates the local project with the `origin` and `github` remotes.
|
|
9. The system adds the framework submodule, installs its skills and hooks (and the plan gate if chosen) and copies the templates.
|
|
10. The system reports a summary of what was created.
|
|
|
|
### Extensions (Alternative / Exception Flows)
|
|
|
|
- 2a. A required tool is missing, or a configuration value is missing or malformed:
|
|
1. The system stops before any change and names the problem without showing a credential.
|
|
- 4a. A token is invalid, an owner does not accept the repository, or the name is taken:
|
|
1. The system stops before creating anything and says which check failed.
|
|
- 4b. SSH to Gitea does not work:
|
|
1. The system uses HTTPS for `origin` and warns that the framework submodule step will fail until SSH is configured.
|
|
- 5a, 6a, 7a. A step fails after an earlier one succeeded:
|
|
1. The system stops and reports what exists, what failed and how to continue.
|
|
- 8a, 9a. The target directory or a target file already exists:
|
|
1. The system asks the Maintainer before replacing it; on no, it skips that item and reports it.
|
|
- 9b. A different `core.hooksPath` is already set:
|
|
1. The system asks before replacing it.
|
|
|
|
### Special Requirements / Business Rules
|
|
|
|
| Step | Rule |
|
|
| --- | --- |
|
|
| 2, 4 | A token never appears in output, logs, command lines, remote URLs or temporary files left behind |
|
|
| 3 | The GitHub owner and the Gitea owner are chosen separately; `GITHUB_USER` is only the authenticating account |
|
|
| 7 | The mirror direction is Gitea to GitHub |
|
|
| 8 | `origin` uses HTTPS derived from `GITEA_URL`, or SSH when the SSH test in step 4 passed |
|
|
| 8, 9 | Nothing is overwritten or deleted without consent, and no commit is made |
|
|
|
|
### Open Issues
|
|
|
|
- The exact SSH `origin` URL form (port 10022) is settled in MIL-003.
|
|
|
|
---
|
|
|
|
[US-001]: ../user-stories.md
|
|
[SA-001]: ../stakeholder-analysis.md
|