Skip to content

Commit 0cd82a9

Browse files
srnicholssrnichols
committed
docs(CONTRIBUTING): restyle with quick nav, workflow, PR checklist, and docs style guide (aligned to repo visuals)
1 parent 2cf9ab7 commit 0cd82a9

File tree

1 file changed

+110
-35
lines changed

1 file changed

+110
-35
lines changed

‎CONTRIBUTING.md‎

Lines changed: 110 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1,52 +1,127 @@
1-
# Contributing to StampsPattern
1+
# 🤝 Contributing to Azure Stamps Pattern
22

3-
Thank you for your interest in contributing to the StampsPattern project!
3+
Thanks for helping improve the Azure Stamps Pattern! This guide explains how to contribute code, docs, and ideas.
44

5-
## How to Contribute
5+
- What’s inside: Workflow, branch/commit guidance, PR checklist, docs style, and tooling
6+
- Best for: Developers, DevOps/Platform engineers, architects, technical writers
7+
- Outcomes: Faster reviews, consistent docs, reliable builds
68

7-
- **Bug Reports & Feature Requests:**
8-
- Use [GitHub Issues](https://github.com/srnichols/StampsPattern/issues) to report bugs or request features.
9+
---
10+
11+
## 🧭 Quick Navigation
912

10-
- **Pull Requests:**
11-
1. Fork the repository and create your branch from `master`.
12-
2. Make your changes with clear, descriptive commit messages.
13-
3. Ensure your code follows the project style and passes any tests.
14-
4. Submit a pull request and describe your changes.
13+
| Section | What you’ll find |
14+
|---------|-------------------|
15+
| [Code of Conduct](#-code-of-conduct) | Community expectations |
16+
| [Before You Start](#-before-you-start) | Fork/clone, branching, tooling |
17+
| [Development Workflow](#-development-workflow) | Branching, commits, tests |
18+
| [Pull Request Checklist](#-pull-request-checklist) | Ready-to-merge criteria |
19+
| [Reporting Issues & Ideas](#-reporting-issues--ideas) | How to open high‑signal issues |
20+
| [Documentation Style Guide](#-documentation-style-guide) | Visual tone and content rules |
21+
| [Security & Responsible Disclosure](#-security--responsible-disclosure) | Security reporting |
22+
| [License](#-license) | MIT |
1523

16-
- **Questions & Ideas:**
17-
- Use [GitHub Issues](https://github.com/srnichols/StampsPattern/issues) with the `question` label for Q&A and ideas.
24+
---
1825

19-
## Code of Conduct
26+
## 🌟 Code of Conduct
2027

21-
Please be respectful and considerate in all interactions. See [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) if available.
28+
Please be respectful and considerate in all interactions. See our [Code of Conduct](./CODE_OF_CONDUCT.md).
2229

2330
---
2431

25-
We appreciate your contributions!
32+
## 🚀 Before You Start
33+
34+
1. Fork this repository and clone your fork.
35+
2. Create a feature branch from `master`:
36+
- Branch naming: `feat/<scope>`, `fix/<scope>`, `docs/<scope>`, `chore/<scope>`
37+
3. Install prerequisites as needed (see project README for scripts and tooling).
38+
39+
> Tip: Use the provided scripts in `scripts/` for local runs and validations where applicable.
40+
41+
---
42+
43+
## 🛠️ Development Workflow
44+
45+
1. Keep changes focused and incremental. Prefer multiple small PRs over one large PR.
46+
2. Use Conventional Commits where practical:
47+
- `feat:`, `fix:`, `docs:`, `chore:`, `refactor:`, `test:`
48+
3. Include clear, descriptive PR titles and summaries.
49+
4. Add or update tests and docs when behavior changes.
50+
5. Ensure CI passes (build, lint, basic checks) if configured.
2651

2752
---
2853

29-
## Documentation Conventions (Style Guide)
54+
## ✅ Pull Request Checklist
55+
56+
- [ ] Clear description of the change and rationale
57+
- [ ] Scope is focused; unrelated changes split out
58+
- [ ] Added/updated docs where needed
59+
- [ ] Added/updated tests (if applicable)
60+
- [ ] No broken links or anchors in docs
61+
- [ ] Follows commit and branch conventions
62+
63+
> For docs PRs, please run the link checker locally before opening the PR:
64+
>
65+
> PowerShell: `pwsh -File ./scripts/verify-doc-links.ps1 -IncludeImages`
66+
67+
---
68+
69+
## 🐛 Reporting Issues & 💡 Ideas
70+
71+
- Use [GitHub Issues](https://github.com/srnichols/StampsPattern/issues).
72+
- Include: expected vs actual behavior, repro steps, environment, logs/screenshots.
73+
- Tag with `bug`, `enhancement`, or `question` as appropriate.
74+
75+
---
3076

31-
Please follow these rules for all Markdown docs under `docs/`:
77+
## 📝 Documentation Style Guide
3278

33-
- What’s inside, Best for, Outcomes
34-
- Use the term “Azure Stamps Pattern” (not just “Stamps Pattern”) when referring to the pattern
35-
- Overall CAF/WAF compliance: 94/100
36-
- WAF Security pillar: 96/100
37-
- Do not state 96/100 as the overall score
38-
- Mermaid blocks use triple backticks with `mermaid`
39-
- Use `\n` inside Mermaid labels instead of `<br/>`
40-
- Keep diagrams minimal and readable
41-
- Use ASCII punctuation (quotes, dashes, ellipses)
42-
- Clear, concise, action‑oriented prose
43-
- Prefer relative links (`./file.md`, `../folder/file.md`)
44-
- Validate links resolve; remove or fix dead links
45-
- Avoid linking to deleted stubs
79+
Use this style for all Markdown under `docs/` and the root `README.md` where applicable.
4680

81+
### Structure
82+
- Start with a short, value‑focused intro.
83+
- Include three bullets near the top: “What’s inside”, “Best for”, “Outcomes”.
84+
- Use clear emoji section headers for scannability (e.g., `## 🧭`, `## 🚀`).
85+
- Prefer compact, actionable prose over long narrative.
86+
87+
### Voice & Wording
88+
- Use “Azure Stamps Pattern” when referring to the solution.
89+
- Keep tone friendly, direct, and enterprise‑ready.
90+
- Use ASCII punctuation and sentence‑case headings.
91+
92+
### Compliance Statements
93+
- Overall CAF/WAF compliance: 94/100
94+
- WAF Security pillar: 96/100
95+
- Do not state 96/100 as the overall score
96+
97+
### Mermaid Diagrams
98+
- All diagrams must use a per‑diagram init with neutral theme:
99+
100+
```
101+
%%{init: {"theme":"neutral","themeVariables":{"background":"transparent","primaryColor":"#E6F0FF","primaryTextColor":"#1F2937","primaryBorderColor":"#94A3B8","lineColor":"#94A3B8","secondaryColor":"#F3F4F6","tertiaryColor":"#DBEAFE","clusterBkg":"#F8FAFC","clusterBorder":"#CBD5E1","edgeLabelBackground":"#F8FAFC","fontFamily":"Segoe UI, Roboto, Helvetica, Arial, sans-serif"}} }%%
102+
```
103+
104+
- Use triple backticks with `mermaid`.
105+
- Prefer `\n` line breaks in labels instead of `<br/>`.
106+
- Keep diagrams minimal and readable.
107+
108+
### Links & Anchors
109+
- Prefer relative links (e.g., `./file.md`, `../folder/file.md`).
110+
- Validate all links; remove or fix dead links.
111+
- Match anchors exactly; verify section titles if you change headings.
112+
113+
---
114+
115+
## 🔒 Security & Responsible Disclosure
116+
117+
If you discover a security issue, please do not open a public issue. Email your Microsoft representative or use private channels to report it responsibly. We’ll coordinate a fix and disclosure plan.
118+
119+
---
120+
121+
## 📄 License
122+
123+
By contributing, you agree that your contributions will be licensed under the [MIT License](./LICENSE).
124+
125+
---
47126

48-
### Pre-PR checklist for docs
49-
- Run the relative link check locally:
50-
- PowerShell: `pwsh -File ./scripts/verify-doc-links.ps1 -IncludeImages`
51-
- Ensure compliance scores are consistent where relevant (Overall 94/100; WAF Security 96/100).
52-
Before opening a PR, skim related guides for consistent wording and anchors. Small inconsistencies are welcome fixes.
127+
Thanks again for contributing — you make this project better for everyone! 🙌

0 commit comments

Comments
 (0)