mirror of
https://github.com/cathrynlavery/diagram-design.git
synced 2026-09-14 16:31:34 +08:00
docs(contributing): add CONTRIBUTING, code of conduct and issue/PR templates
Add CONTRIBUTING.md covering all validation gates and contribution workflows, CODE_OF_CONDUCT.md (Contributor Covenant 2.1), GitHub issue templates (bug/feature), and a pull request template; add a Contributing section to the README.
This commit is contained in:
Vitaliy Filyuchkov
@@ -0,0 +1,66 @@
|
||||
name: Bug report
|
||||
description: A diagram, script, or import path misbehaves — report it so we can fix it.
|
||||
title: "[Bug]: "
|
||||
labels: ["bug"]
|
||||
body:
|
||||
- type: markdown
|
||||
attributes:
|
||||
value: |
|
||||
Thanks for reporting. Before submitting, check that this isn't an already-open issue.
|
||||
- type: dropdown
|
||||
id: area
|
||||
attributes:
|
||||
label: Area
|
||||
description: What part of the project is affected?
|
||||
options:
|
||||
- A diagram example
|
||||
- Style guide / skin / linter
|
||||
- draw.io import
|
||||
- Mermaid import
|
||||
- Export (SVG / PNG)
|
||||
- Documentation
|
||||
- CI / tooling
|
||||
- Other
|
||||
validations:
|
||||
required: true
|
||||
- type: textarea
|
||||
id: description
|
||||
attributes:
|
||||
label: What happened?
|
||||
description: Describe the unexpected behavior. Include what you expected instead.
|
||||
placeholder: "The linter accepts a diagram that breaks the accessible SVG contract…"
|
||||
validations:
|
||||
required: true
|
||||
- type: textarea
|
||||
id: repro
|
||||
attributes:
|
||||
label: Steps to reproduce
|
||||
description: Concrete steps — commands, file names, and inputs matter here.
|
||||
placeholder: |
|
||||
1. Run `python3 scripts/lint-skin.py <file>`
|
||||
2. …
|
||||
validations:
|
||||
required: true
|
||||
- type: input
|
||||
id: environment
|
||||
attributes:
|
||||
label: Environment
|
||||
description: OS, Python version, agent (Claude Code / Codex / Pi) if relevant
|
||||
placeholder: "macOS 14, Python 3.11, Claude Code"
|
||||
- type: checkboxes
|
||||
id: gates
|
||||
attributes:
|
||||
label: Validation gates
|
||||
description: If relevant, which gates have you already run?
|
||||
options:
|
||||
- label: "`python3 scripts/test-lint-a11y.py`"
|
||||
- label: "`python3 scripts/lint-skin.py --all --baseline`"
|
||||
- label: "`python3 scripts/verify-drawio-import.py`"
|
||||
- label: "`python3 scripts/verify-mermaid-import.py`"
|
||||
- label: "I haven't run any gates"
|
||||
- type: textarea
|
||||
id: logs
|
||||
attributes:
|
||||
label: Relevant output
|
||||
description: Paste error messages or linter findings, trimmed to what matters.
|
||||
render: text
|
||||
@@ -0,0 +1,5 @@
|
||||
blank_issues_enabled: true
|
||||
contact_links:
|
||||
- name: Security vulnerability
|
||||
url: https://github.com/cathrynlavery/diagram-design/security/advisories/new
|
||||
about: Report a suspected vulnerability privately — do not open a public issue for it.
|
||||
@@ -0,0 +1,45 @@
|
||||
name: Feature request
|
||||
description: Suggest a new diagram type, primitive, or improvement.
|
||||
title: "[Feature]: "
|
||||
labels: ["enhancement"]
|
||||
body:
|
||||
- type: markdown
|
||||
attributes:
|
||||
value: |
|
||||
Ideas are welcome. Before submitting, check the README's "When *not* to use this skill" section — sometimes the right answer is a table, not a diagram.
|
||||
- type: textarea
|
||||
id: problem
|
||||
attributes:
|
||||
label: What are you trying to show?
|
||||
description: Describe the situation and what the reader needs to understand. A sketch or ASCII mock helps a lot.
|
||||
placeholder: "I want to show how... and the reader should see..."
|
||||
validations:
|
||||
required: true
|
||||
- type: textarea
|
||||
id: proposal
|
||||
attributes:
|
||||
label: Proposed solution
|
||||
description: How could the skill serve this? A new type, a primitive, a change to an existing one, docs?
|
||||
placeholder: "A new `type-*.md` for …, or an extension of …"
|
||||
- type: dropdown
|
||||
id: scope
|
||||
attributes:
|
||||
label: Scope
|
||||
description: Roughly how much surface does this touch?
|
||||
options:
|
||||
- New diagram type (reference + 3 examples + gallery)
|
||||
- New or changed primitive
|
||||
- Import grammar support
|
||||
- Tooling / scripts / CI
|
||||
- Documentation only
|
||||
- Not sure yet — help me scope it
|
||||
validations:
|
||||
required: true
|
||||
- type: checkboxes
|
||||
id: philosophy
|
||||
attributes:
|
||||
label: Design-system fit
|
||||
description: Features in this project must fit the editorial philosophy in SKILL.md §1–§2.
|
||||
options:
|
||||
- label: "I've checked the anti-patterns and 'When not to use' — this still seems worth drawing"
|
||||
- label: "I'm willing to contribute the implementation or pair with a maintainer"
|
||||
@@ -0,0 +1,26 @@
|
||||
## What does this PR do?
|
||||
|
||||
<!-- One or two sentences: what changed and why. -->
|
||||
|
||||
## Validation gates
|
||||
|
||||
<!-- Mark what you ran and that it passed. CI runs all of these on the PR too. -->
|
||||
|
||||
- [ ] `python3 scripts/test-lint-a11y.py`
|
||||
- [ ] `python3 scripts/lint-skin.py --all --baseline`
|
||||
- [ ] `python3 scripts/verify-sequence-oauth.py`
|
||||
- [ ] `python3 scripts/verify-drawio-import.py`
|
||||
- [ ] `python3 scripts/verify-mermaid-import.py`
|
||||
- [ ] `git diff --exit-code` green after `python3 scripts/build-icons.py` (if icons changed)
|
||||
- [ ] Docs updated in the same PR where behavior changed
|
||||
|
||||
## Checklist
|
||||
|
||||
- [ ] No new entries added to `scripts/lint-skin-baseline.txt`
|
||||
- [ ] Generated and source files are consistent (extractor ↔ verifier ↔ reference ↔ command)
|
||||
- [ ] Accessible SVG contract satisfied for new/changed examples
|
||||
- [ ] Code of Conduct respected
|
||||
|
||||
## Related issues
|
||||
|
||||
<!-- Link any issues this closes, e.g. "Closes #12". -->
|
||||
@@ -0,0 +1,134 @@
|
||||
# Contributor Covenant Code of Conduct
|
||||
|
||||
## Our Pledge
|
||||
|
||||
We as members, contributors, and leaders pledge to make participation in our
|
||||
community a harassment-free experience for everyone, regardless of age, body
|
||||
size, visible or invisible disability, ethnicity, sex characteristics, gender
|
||||
identity and expression, level of experience, education, socio-economic status,
|
||||
nationality, personal appearance, race, caste, color, religion, or sexual
|
||||
identity and orientation.
|
||||
|
||||
We pledge to act and interact in ways that contribute to an open, welcoming,
|
||||
diverse, inclusive, and healthy community.
|
||||
|
||||
## Our Standards
|
||||
|
||||
Examples of behavior that contributes to a positive environment for our
|
||||
community include:
|
||||
|
||||
- Demonstrating empathy and kindness toward other people
|
||||
- Being respectful of differing opinions, viewpoints, and experiences
|
||||
- Giving and gracefully accepting constructive feedback
|
||||
- Accepting responsibility and apologizing to those affected by our mistakes,
|
||||
and learning from the experience
|
||||
- Focusing on what is best not just for us as individuals, but for the overall
|
||||
community
|
||||
|
||||
Examples of unacceptable behavior include:
|
||||
|
||||
- The use of sexualized language or imagery, and sexual attention or advances of
|
||||
any kind
|
||||
- Trolling, insulting or derogatory comments, and personal or political attacks
|
||||
- Public or private harassment
|
||||
- Publishing others' private information, such as a physical or email address,
|
||||
without their explicit permission
|
||||
- Other conduct which could reasonably be considered inappropriate in a
|
||||
professional setting
|
||||
|
||||
## Enforcement Responsibilities
|
||||
|
||||
Community leaders are responsible for clarifying and enforcing our standards of
|
||||
acceptable behavior and will take appropriate and fair corrective action in
|
||||
response to any behavior that they deem inappropriate, threatening, offensive,
|
||||
or harmful.
|
||||
|
||||
Community leaders have the right and responsibility to remove, edit, or reject
|
||||
comments, commits, code, wiki edits, issues, and other contributions that are
|
||||
not aligned to this Code of Conduct, and will communicate reasons for moderation
|
||||
decisions when appropriate.
|
||||
|
||||
## Scope
|
||||
|
||||
This Code of Conduct applies within all community spaces, and also applies when
|
||||
an individual is officially representing the community in public spaces.
|
||||
Examples of representing our community include using an official email address,
|
||||
posting via an official social media account, or acting as an appointed
|
||||
representative at an online or offline event.
|
||||
|
||||
## Enforcement
|
||||
|
||||
Instances of abusive, harassing, or otherwise unacceptable behavior may be
|
||||
reported to the community leaders responsible for enforcement at
|
||||
[github.com/cathrynlavery/diagram-design/issues](https://github.com/cathrynlavery/diagram-design/issues)
|
||||
or via private vulnerability reporting ([SECURITY.md](SECURITY.md) links the
|
||||
private path). All complaints will be reviewed and investigated promptly and
|
||||
fairly.
|
||||
|
||||
All community leaders are obligated to respect the privacy and security of the
|
||||
reporter of any incident.
|
||||
|
||||
## Enforcement Guidelines
|
||||
|
||||
Community leaders will follow these Community Impact Guidelines in determining
|
||||
the consequences for any action they deem in violation of this Code of Conduct:
|
||||
|
||||
### 1. Correction
|
||||
|
||||
**Community Impact**: Use of inappropriate language or other behavior deemed
|
||||
unprofessional or unwelcome in the community.
|
||||
|
||||
**Consequence**: A private, written warning from community leaders, providing
|
||||
clarity around the nature of the violation and an explanation of why the
|
||||
behavior was inappropriate. A public apology may be requested.
|
||||
|
||||
### 2. Warning
|
||||
|
||||
**Community Impact**: A violation through a single incident or series of
|
||||
actions.
|
||||
|
||||
**Consequence**: A warning with consequences for continued behavior. No
|
||||
interaction with the people involved, including unsolicited interaction with
|
||||
those enforcing the Code of Conduct, for a specified period of time. This
|
||||
includes avoiding interactions in community spaces as well as external channels
|
||||
like social media. Violating these terms may lead to a temporary or permanent
|
||||
ban.
|
||||
|
||||
### 3. Temporary Ban
|
||||
|
||||
**Community Impact**: A serious violation of community standards, including
|
||||
sustained inappropriate behavior.
|
||||
|
||||
**Consequence**: A temporary ban from any sort of interaction or public
|
||||
communication with the community for a specified period of time. No public or
|
||||
private interaction with the people involved, including unsolicited interaction
|
||||
with those enforcing the Code of Conduct, is allowed during this period.
|
||||
Violating these terms may lead to a permanent ban.
|
||||
|
||||
### 4. Permanent Ban
|
||||
|
||||
**Community Impact**: Demonstrating a pattern of violation of community
|
||||
standards, including sustained inappropriate behavior, harassment of an
|
||||
individual, or aggression toward or disparagement of classes of individuals.
|
||||
|
||||
**Consequence**: A permanent ban from any sort of public interaction within the
|
||||
community.
|
||||
|
||||
## Attribution
|
||||
|
||||
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
|
||||
version 2.1, available at
|
||||
[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
|
||||
|
||||
Community Impact Guidelines were inspired by
|
||||
[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
|
||||
|
||||
For answers to common questions about this code of conduct, see the FAQ at
|
||||
[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
|
||||
[https://www.contributor-covenant.org/translations][translations].
|
||||
|
||||
[homepage]: https://www.contributor-covenant.org
|
||||
[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
|
||||
[Mozilla CoC]: https://github.com/mozilla/diversity
|
||||
[FAQ]: https://www.contributor-covenant.org/faq
|
||||
[translations]: https://www.contributor-covenant.org/translations
|
||||
+136
@@ -0,0 +1,136 @@
|
||||
# Contributing to Diagram Design
|
||||
|
||||
Thanks for wanting to contribute — this project only gets better with more eyes on it.
|
||||
|
||||
Please read [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) first. All contributions are expected to keep the community welcoming.
|
||||
|
||||
---
|
||||
|
||||
## What this project is
|
||||
|
||||
Diagram Design is an agent skill (Claude Code, Codex, Pi) that produces editorial-quality diagrams as self-contained HTML files. The repo is documentation-first: `skills/diagram-design/SKILL.md` is the index, each of the 27 diagram types has its own reference file, and the extractor scripts in `skills/diagram-design/scripts/` turn draw.io and Mermaid sources into a structured IR.
|
||||
|
||||
See [README.md](README.md) for the full picture, including the design system and the import/export flows.
|
||||
|
||||
---
|
||||
|
||||
## Before you start
|
||||
|
||||
- **Create an issue first** for anything non-trivial (new type, behavior change, import grammar work). Small fixes and docs can go straight to a PR.
|
||||
- **Work on a branch** — never commit directly to `main`.
|
||||
- **Keep the scope tight.** One PR = one concern. Mixing a new diagram type with a docs rewrite makes review slow.
|
||||
- **Python 3.10+ is required** for the development scripts (CI runs 3.11).
|
||||
|
||||
---
|
||||
|
||||
## Validation gates
|
||||
|
||||
Every validation gate below must pass before a PR is ready. They also run automatically as GitHub Actions CI (`.github/workflows/ci.yml`).
|
||||
|
||||
| What it checks | Command |
|
||||
|---|---|
|
||||
| Accessible SVG contract (unit tests for the a11y linter) | `python3 scripts/test-lint-a11y.py` |
|
||||
| Skin conformance of every example (colors, fonts, a11y) | `python3 scripts/lint-skin.py --all --baseline` |
|
||||
| A single file, e.g. a new example | `python3 scripts/lint-skin.py skills/diagram-design/assets/example-my-type.html` |
|
||||
| Sequence-doc consistency (ATL fragments, budgets) | `python3 scripts/verify-sequence-oauth.py` |
|
||||
| draw.io import path (real extractor vs fixtures + docs sync) | `python3 scripts/verify-drawio-import.py` |
|
||||
| Mermaid import path (grammars, adversarial input, caps, docs sync) | `python3 scripts/verify-mermaid-import.py` |
|
||||
| Generated icon assets are up to date (`icons.html`, `primitive-icons.md`) | `python3 scripts/build-icons.py` then `git diff --exit-code` on the two generated files |
|
||||
|
||||
Run them all at once before pushing:
|
||||
|
||||
```bash
|
||||
python3 scripts/test-lint-a11y.py \
|
||||
&& python3 scripts/lint-skin.py --all --baseline \
|
||||
&& python3 scripts/verify-sequence-oauth.py \
|
||||
&& python3 scripts/verify-drawio-import.py \
|
||||
&& python3 scripts/verify-mermaid-import.py
|
||||
```
|
||||
|
||||
### If a gate fails
|
||||
|
||||
- **`lint-skin.py`:** the failure message names the file, line, and category (`color`, `font-family`, `a11y`, `external-asset`, `pure-black`, `script`). Colors must come from the palette in `skills/diagram-design/references/style-guide.md`; fonts from the allowed list; diagrams must satisfy the accessible SVG contract (see below).
|
||||
- **`verify-*.py`:** the extractor's real behavior no longer matches its fixture or the documentation, or the reference/command/prompt wiring drifted. Fix the source of truth — do not widen a test to avoid a failure.
|
||||
- **Icon assets:** you changed `scripts/vendor/icons/` or `scripts/build-icons.py` and the generated files went stale. Rerun `python3 scripts/build-icons.py` and commit the regenerated files.
|
||||
|
||||
Do **not** add a file to `scripts/lint-skin-baseline.txt` to get your example through. The baseline exists only for legacy pre-2.0 examples that legitimately predate the current skin, and it still receives a11y checks.
|
||||
|
||||
---
|
||||
|
||||
## The accessible SVG contract (a11y)
|
||||
|
||||
Every diagram `<svg>` must satisfy the contract enforced by the linter:
|
||||
|
||||
1. `role="img"` and `aria-labelledby` naming the `<title>` **and** `<desc>`.
|
||||
2. `<title>` is the **first child** of `<svg>` (before `<defs>`).
|
||||
3. IDs are prefixed per diagram and variant: `<slug>-title` / `<slug>-desc` — for `example-loop-dark.html` the slug is `loop-dark`, so the IDs are `loop-dark-title` / `loop-dark-desc`. Bare `title`/`desc` IDs and duplicate IDs are rejected.
|
||||
4. `<title>` is the short subject name (≈ the `<h1>`, ≤ 60 chars); `<desc>` is one sentence describing the *content*, not the geometry.
|
||||
5. Purely decorative SVGs (`aria-hidden="true"`) are exempt.
|
||||
|
||||
The contract lives in `scripts/lint-skin.py` (`lint_accessible_svgs`) and is unit-tested by `scripts/test-lint-a11y.py`. When in doubt, pattern-match an existing example.
|
||||
|
||||
---
|
||||
|
||||
## Working on examples (diagrams)
|
||||
|
||||
Every diagram type ships three variants: minimal light (`example-<type>.html`), minimal dark (`example-<type>-dark.html`), and full editorial (`example-<type>-full.html`).
|
||||
|
||||
1. Copy the closest template (`skills/diagram-design/assets/template.html`, `template-dark.html`, or `template-full.html`).
|
||||
2. Load the matching `references/type-<name>.md` and follow its layout conventions.
|
||||
3. Replace the eyebrow, h1, and SVG body; replace the `[diagram-slug]` placeholders with your file's slug and keep the `<title>`/`<desc>` slots filled.
|
||||
4. Run the taste gate in `SKILL.md` §9, then the linter:
|
||||
|
||||
```bash
|
||||
python3 scripts/lint-skin.py skills/diagram-design/assets/example-my-type.html
|
||||
```
|
||||
|
||||
New examples should be added to the gallery (`assets/index.html`) so they stay browsable.
|
||||
|
||||
## Adding a new diagram type
|
||||
|
||||
1. Write `skills/diagram-design/references/type-<name>.md` — layout conventions, anti-patterns, and a worked pattern for that type. Mirror an existing reference's structure.
|
||||
2. Add the row to the selection table in `skills/diagram-design/SKILL.md` §3.
|
||||
3. Add the three example variants (see above) and register them in the gallery.
|
||||
4. Run the full gate suite — new examples are linted automatically by `--all`.
|
||||
|
||||
## Changing the icon set
|
||||
|
||||
Icons are generated, never hand-edited:
|
||||
|
||||
1. Add or replace the source SVG in `scripts/vendor/icons/<source>/` (`tabler/`, `simple/`, …). Keep license provenance in `THIRD_PARTY_LICENSES.md` accurate.
|
||||
2. Regenerate and verify:
|
||||
|
||||
```bash
|
||||
python3 scripts/build-icons.py
|
||||
git diff --exit-code -- skills/diagram-design/assets/icons.html skills/diagram-design/references/primitive-icons.md
|
||||
```
|
||||
|
||||
## Touching the import paths
|
||||
|
||||
- draw.io: `skills/diagram-design/scripts/drawio_extract.py` — must pass `scripts/verify-drawio-import.py`, which drives the extractor against `scripts/fixtures/sample-architecture.drawio` in all four container formats (raw XML, deflate+base64, PNG-embedded, SVG-embedded).
|
||||
- Mermaid: `skills/diagram-design/scripts/mermaid_extract.py` — must pass `scripts/verify-mermaid-import.py`, which covers every supported grammar, multi-block Markdown, adversarial labels, trust-boundary behavior, resource caps, and named failures.
|
||||
|
||||
Both scripts treat their input as **untrusted data** — they never render, fetch, or execute source content. Keep it that way. If you add a grammar or a new security boundary, extend the corresponding verifier with a fixture before merging.
|
||||
|
||||
Documentation and wiring must stay in sync: the import references, `SKILL.md` §11, the slash commands in `commands/`, and the Pi prompt templates in `prompts/` each describe the same flows. The verifiers check this — keep both sides updated in one PR.
|
||||
|
||||
## Documentation
|
||||
|
||||
Most of this repo *is* documentation. When behavior changes, update the affected reference files and the README in the same PR. Loose ends here are what the verifiers and reviewers will catch.
|
||||
|
||||
---
|
||||
|
||||
## Commit and PR conventions
|
||||
|
||||
Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/): `type(scope): summary`, e.g. `fix(import): support current Mermaid syntax`, `ci: verify Mermaid imports`, `docs(onboarding): clarify the URL flow`. Keep summaries short and imperative.
|
||||
|
||||
A good PR:
|
||||
|
||||
- has a clear title and a description that says *what* changed and *why*;
|
||||
- mentions how you tested it (which gates you ran);
|
||||
- keeps generated and source files consistent (extractor + verifier + reference + command in one change);
|
||||
- is rebased on `main` and green on CI.
|
||||
|
||||
## Questions?
|
||||
|
||||
Open a discussion or comment on the relevant issue. If it's about security, use the private reporting path in [SECURITY.md](SECURITY.md).
|
||||
@@ -408,6 +408,12 @@ Before drawing, ask: *would a reader learn more from this than from a well-writt
|
||||
|
||||
---
|
||||
|
||||
## Contributing
|
||||
|
||||
Contributions are welcome — new diagram types, import grammar support, examples, docs, and tooling. See [CONTRIBUTING.md](CONTRIBUTING.md) for the validation gates and workflows, and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community standards.
|
||||
|
||||
---
|
||||
|
||||
## About
|
||||
|
||||
Made by **Cathryn Lavery** — founder of [BestSelf.co](https://bestself.co?utm_source=diagram-design&utm_medium=readme&utm_campaign=github&utm_content=bio). I write about AI, entrepreneurship, and designing nice-looking things at [littlemight.com](https://littlemight.com?utm_source=diagram-design&utm_medium=readme&utm_campaign=github&utm_content=bio) — blog + newsletter.
|
||||
|
||||
Reference in New Issue
Block a user