Skip to content

Commit a687f60

Browse files
CRAFTFrameworkCRAFTFramework
authored
Update CONTRIBUTING.md
1 parent ea470e0 commit a687f60

File tree

1 file changed

+88
-100
lines changed

1 file changed

+88
-100
lines changed

‎CONTRIBUTING.md‎

Lines changed: 88 additions & 100 deletions
Original file line numberDiff line numberDiff line change
@@ -1,146 +1,134 @@
1-
Contributing to CRAFT (Alpha)
1+
# Contributing to CRAFT (Alpha)
22

3-
Status: Early Alpha • Sole maintainer with 0–2 hrs/week • Org-wide policy for CRAFTFramework
3+
> **Status:** Early **Alpha** • **Sole maintainer** with **0–2 hrs/week** • Org-wide policy for [CRAFTFramework](https://github.com/CRAFTFramework)
4+
> **TL;DR:** We’re keeping the contribution surface **very small** for now so we can focus on building. More avenues will open as we move from **Alpha → Beta → GA**.
45
5-
TL;DR: We’re keeping the contribution surface very small for now so we can focus on building. More avenues will open as we move from Alpha → Beta → GA.
6+
---
67

7-
Why contributions are limited right now
8+
## Why contributions are limited right now
89

9-
CRAFT is a brand-new framework with evolving foundations (four-file model, comment system, cookbook, etc.). With limited weekly time (generally Mondays) I need to prioritize shipping core functionality and docs. To keep maintenance overhead near zero, I’m opening only the lowest-touch channels at this stage.
10+
CRAFT is a brand-new framework with evolving foundations (four-file model, comment system, cookbook, etc.). With limited weekly time (generally Mondays) I need to prioritize shipping core functionality and docs. To keep maintenance overhead near **zero**, I’m opening only the lowest-touch channels at this stage.
1011

11-
At-a-glance: What’s open in Alpha
12-
Area Alpha policy Notes
13-
GitHub Discussions ✅ Open Use for Q&A, ideas, and roadmap input.
14-
Issues (Bug Reports) ✅ **Open via Issue Form Must use the Bug form (see required fields below).
15-
Pull Requests (code/features) ❌ Closed to unsolicited PRs PRs require pre-approval on a linked Issue/Discussion.
16-
PRs (tiny docs typos ≤ 5 lines) ✅ Allowed No prior approval required; may be merged at maintainer discretion.
17-
Security reports ✅ Email only Send to rich.ketelsen@bestbuy.com
18-
. Public security issues will be closed.
12+
---
1913

20-
Triage cadence: Best-effort; we typically review on Mondays.
14+
## At-a-glance: What’s open in Alpha
2115

22-
How to help today
23-
1) Start or join a Discussion
16+
| Area | Alpha policy | Notes |
17+
|---|---|---|
18+
| **GitHub Discussions** | ✅ **Open** | Use for Q&A, ideas, and roadmap input. |
19+
| **Issues (Bug Reports)** | ✅ **Open via Issue Form** | Must use the **Bug** form (see required fields below). |
20+
| **Pull Requests (code/features)** | ❌ **Closed to unsolicited PRs** | PRs require **pre-approval** on a linked Issue/Discussion. |
21+
| **PRs (tiny docs typos ≤ 5 lines)** | ✅ **Allowed** | No prior approval required; may be merged at maintainer discretion. |
22+
| **Security reports** | ✅ **Email only** | Send to **rich.ketelsen@bestbuy.com**. Public security issues will be closed. |
2423

25-
Ask questions, propose ideas, or discuss patterns/workflows you’d like to see.
24+
**Triage cadence:** *Best-effort; we typically review on **Mondays**.*
2625

27-
Please search first to avoid duplicates.
26+
---
2827

29-
2) File a Bug Report (Issue Form)
28+
## How to help **today**
3029

31-
Use the Bug issue form. The following fields are required so I can reproduce quickly:
30+
### 1) Start or join a **Discussion**
31+
- Ask questions, propose ideas, or discuss patterns/workflows you’d like to see.
32+
- Please search first to avoid duplicates.
3233

33-
Steps to reproduce
34+
### 2) File a **Bug Report** (Issue Form)
35+
Use the **Bug** issue form. The following fields are **required** so I can reproduce quickly:
36+
- **Steps to reproduce**
37+
- **Which four CRAFT files & versions you used** (Project file, AI-CHAT-HISTORY file, Framework Spec, Core Cookbook)
38+
- **Expected vs actual behavior**
39+
- **Minimal reproduction** (link to a gist or paste the exact prompts/sections you used)
40+
- **Environment** (chat model and date of run)
3441

35-
Which four CRAFT files & versions you used (Project file, AI-CHAT-HISTORY file, Framework Spec, Core Cookbook)
42+
> Feature requests should go to **Discussions (Ideas)** for now—**not** Issues.
3643
37-
Expected vs actual behavior
44+
### 3) Submit a **tiny docs typo PR** (≤ 5 changed lines)
45+
- Fixes for wording/typos are welcome without pre-approval.
46+
- For larger docs changes, please open a Discussion first.
3847

39-
Minimal reproduction (link to a gist or paste the exact prompts/sections you used)
48+
---
4049

41-
Environment (chat model and date of run)
50+
## What is **not** open yet
4251

43-
Feature requests should go to Discussions (Ideas) for now—not Issues.
52+
- **Unsolicited code/feature PRs** (will be closed with a friendly note to discuss first).
53+
- **New example projects** via PR (will open in Beta; for now, please suggest ideas in Discussions).
54+
- **Expansive docs rewrites** (please discuss first).
4455

45-
3) Submit a tiny docs typo PR (≤ 5 changed lines)
56+
If you believe your change is small, self-contained, and time-saving for maintainers, open a Discussion describing scope; I may tag it **approved-for-pr** before you open a PR.
4657

47-
Fixes for wording/typos are welcome without pre-approval.
58+
---
4859

49-
For larger docs changes, please open a Discussion first.
60+
## Security policy (summary)
5061

51-
What is not open yet
62+
- Please **email** all security or responsible disclosure reports to **rich.ketelsen@bestbuy.com**.
63+
- For confidentiality, **do not** open public Issues or Discussions about security.
64+
- Public security reports will be closed with a note to email.
5265

53-
Unsolicited code/feature PRs (will be closed with a friendly note to discuss first).
66+
---
5467

55-
New example projects via PR (will open in Beta; for now, please suggest ideas in Discussions).
68+
## Maintainer bandwidth & acknowledgement
5669

57-
Expansive docs rewrites (please discuss first).
70+
- I maintain this project **part-time** and typically review activity on **Mondays**.
71+
- I’m a **beginner to GitHub** and will be learning (with AI assistance) as the project evolves.
72+
- If replies are slow, it’s because I’m prioritizing core stability so we can welcome broader contributions sooner.
5873

59-
If you believe your change is small, self-contained, and time-saving for maintainers, open a Discussion describing scope; I may tag it approved-for-pr before you open a PR.
74+
---
6075

61-
Security policy (summary)
76+
## Roadmap for opening contributions
6277

63-
Please email all security or responsible disclosure reports to rich.ketelsen@bestbuy.com
64-
.
78+
**Alpha (now)**
79+
- Discussions open; Bug Issues via form; tiny docs typo PRs allowed.
80+
- No unsolicited code PRs.
6581

66-
For confidentiality, do not open public Issues or Discussions about security.
82+
**Beta (later)**
83+
- Open **small Docs/Examples PRs** (style & structure guidelines provided).
84+
- Publish **good first issues** for docs/examples.
85+
- Light review SLA (e.g., weekly).
6786

68-
Public security reports will be closed with a note to email.
87+
**GA (later)**
88+
- Open **code PRs** with tests/examples, review checklist, and CI requirements.
89+
- Clear maintainer review & merge policy, broader labels, and contributor recognition.
6990

70-
Maintainer bandwidth & acknowledgement
91+
---
7192

72-
I maintain this project part-time and typically review activity on Mondays.
93+
## Low-touch templates & guardrails (either enabled now or planned)
7394

74-
I’m a beginner to GitHub and will be learning (with AI assistance) as the project evolves.
95+
To keep overhead near **0–2 hrs/week**, we use (or plan to use) the following:
7596

76-
If replies are slow, it’s because I’m prioritizing core stability so we can welcome broader contributions sooner.
97+
- **Issue Forms**: *Bug* (required fields listed above) and *Docs Typo*.
98+
- **PR Template**: Politely explains our **Alpha** policy and asks for prior approval via linked Discussion/Issue.
99+
- **CODEOWNERS**: Assigns review to the maintainer by default.
100+
- **Branch Protection**: Requires at least one approval for merges.
101+
- **Stale bot (planned)**: Inactive issues auto-closed after **30 days** with a friendly reminder.
77102

78-
Roadmap for opening contributions
103+
> If any of the above isn’t enabled yet, it’s on the near-term checklist; the policy still applies.
79104
80-
Alpha (now)
105+
---
81106

82-
Discussions open; Bug Issues via form; tiny docs typo PRs allowed.
107+
## How to request **pre-approval** for a PR
108+
1. Open a **Discussion** titled `Proposal: <short name>`.
109+
2. Include scope, why it’s needed now, and (if bug fix) a link to the Bug Issue.
110+
3. I’ll label it **approved-for-pr** if it’s ready; otherwise we’ll clarify next steps.
83111

84-
No unsolicited code PRs.
112+
---
85113

86-
Beta (later)
114+
## Code of Conduct & License
87115

88-
Open small Docs/Examples PRs (style & structure guidelines provided).
116+
- **Code of Conduct:** This project follows an org-wide CoC. Please read and abide by it.
117+
- **License:** Unless noted otherwise, contributions land under the repository’s **Business Source License 1.1 (BSL)** with the stated future change date (Apache 2.0 on conversion). See `LICENSE` at the repo root.
89118

90-
Publish good first issues for docs/examples.
119+
---
91120

92-
Light review SLA (e.g., weekly).
93-
94-
GA (later)
95-
96-
Open code PRs with tests/examples, review checklist, and CI requirements.
97-
98-
Clear maintainer review & merge policy, broader labels, and contributor recognition.
99-
100-
Low-touch templates & guardrails (either enabled now or planned)
101-
102-
To keep overhead near 0–2 hrs/week, we use (or plan to use) the following:
103-
104-
Issue Forms: Bug (required fields listed above) and Docs Typo.
105-
106-
PR Template: Politely explains our Alpha policy and asks for prior approval via linked Discussion/Issue.
107-
108-
CODEOWNERS: Assigns review to the maintainer by default.
109-
110-
Branch Protection: Requires at least one approval for merges.
111-
112-
Stale bot (planned): Inactive issues auto-closed after 30 days with a friendly reminder.
113-
114-
If any of the above isn’t enabled yet, it’s on the near-term checklist; the policy still applies.
115-
116-
How to request pre-approval for a PR
117-
118-
Open a Discussion titled Proposal: <short name>.
119-
120-
Include scope, why it’s needed now, and (if bug fix) a link to the Bug Issue.
121-
122-
I’ll label it approved-for-pr if it’s ready; otherwise we’ll clarify next steps.
123-
124-
Code of Conduct & License
125-
126-
Code of Conduct: This project follows an org-wide CoC. Please read and abide by it.
127-
128-
License: Unless noted otherwise, contributions land under the repository’s Business Source License 1.1 (BSL) with the stated future change date (Apache 2.0 on conversion). See LICENSE at the repo root.
129-
130-
Thank you
121+
## Thank you
131122

132123
Even simple acts—asking a good question, filing a high-quality bug, fixing a typo—help move CRAFT forward. Thanks for understanding the constraints during Alpha and for helping us build toward a welcoming, full-featured contribution process. 🙏
133124

134-
Quick reference
135-
136-
Discussions: Q&A, ideas, proposals
137-
138-
Issues: Bug reports only (form required)
139-
140-
PRs: Tiny docs typos only (≤ 5 lines) • All others need pre-approval
141-
142-
Security: Email rich.ketelsen@bestbuy.com
125+
---
143126

144-
Acknowledgement: Best-effort; typically Mondays
127+
### Quick reference
145128

146-
Org-wide: Applies to all repos under CRAFTFramework unless overridden locally
129+
- **Discussions:** Q&A, ideas, proposals
130+
- **Issues:** **Bug reports** only (form required)
131+
- **PRs:** Tiny docs typos only (≤ 5 lines) • All others need **pre-approval**
132+
- **Security:** Email **rich.ketelsen@bestbuy.com**
133+
- **Acknowledgement:** *Best-effort; typically **Mondays***
134+
- **Org-wide:** Applies to all repos under **CRAFTFramework** unless overridden locally

0 commit comments

Comments
 (0)