Skip to content

Commit 3dd04cd

Browse files
sepehr-safarisepehr-safari
committed
docs: add CONTRIBUTING, CODE_OF_CONDUCT, ROADMAP, README, SECURITY
- CONTRIBUTING.md: setup, conventions, PR process, AI-assisted dev section (tool-neutral, no AI tool references) - CODE_OF_CONDUCT.md: Contributor Covenant 2.1 - ROADMAP.md: milestone summary (M0 through v1.0.0) - README.md: description, badges, architecture, quickstart, support section (USDT/BEP20), links - SECURITY.md: vulnerability reporting via GitHub private advisories, security principles for untrusted input handling - CURRENT_STATE.md: updated to reflect all M0 PRs Closes #9, closes #10, closes #11
1 parent 8f0045f commit 3dd04cd

6 files changed

Lines changed: 610 additions & 6 deletions

File tree

‎CODE_OF_CONDUCT.md‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
# Contributor Covenant Code of Conduct
2+
3+
## Our Pledge
4+
5+
We as members, contributors, and leaders pledge to make participation in our
6+
community a harassment-free experience for everyone, regardless of age, body
7+
size, visible or invisible disability, ethnicity, sex characteristics, gender
8+
identity and expression, level of experience, education, socio-economic status,
9+
nationality, personal appearance, race, caste, color, religion, or sexual
10+
identity and orientation.
11+
12+
We pledge to act and interact in ways that contribute to an open, welcoming,
13+
diverse, inclusive, and healthy community.
14+
15+
## Our Standards
16+
17+
Examples of behavior that promotes a positive environment:
18+
19+
* Demonstrating empathy and kindness toward other people
20+
* Being respectful of differing opinions, viewpoints, and experiences
21+
* Giving and gracefully accepting constructive feedback
22+
* Accepting responsibility, apologizing to those affected by our mistakes,
23+
and learning from the experience
24+
* Focusing on what is best for the overall community
25+
26+
Examples of unacceptable behavior:
27+
28+
* The use of sexualized language or imagery, and sexual attention or advances
29+
of any kind
30+
* Trolling, insulting or derogatory comments, and personal or political attacks
31+
* Public or private harassment
32+
* Publishing others' private information, such as a physical or email address,
33+
without their explicit permission
34+
* Other conduct which could reasonably be considered inappropriate in a
35+
professional setting
36+
37+
## Enforcement Responsibilities
38+
39+
Community leaders are responsible for clarifying and enforcing our standards
40+
of acceptable behavior and will take appropriate and fair corrective action in
41+
response to any behavior that they deem inappropriate, threatening, offensive,
42+
or harmful.
43+
44+
Community leaders have the right and responsibility to remove, edit, or reject
45+
comments, commits, code, wiki edits, issues, and other contributions that are
46+
not aligned to this Code of Conduct, and will communicate reasons for moderation
47+
decisions when appropriate.
48+
49+
## Scope
50+
51+
This Code of Conduct applies within all community spaces, and also applies when
52+
an individual is officially representing the community in public spaces.
53+
Examples of representing our community include using an official email address,
54+
posting via an official social media account, or acting as an appointed
55+
representative at an online or offline event.
56+
57+
## Enforcement
58+
59+
Instances of abusive, harassing, or otherwise unacceptable behavior may be
60+
reported via [GitHub's private reporting channel](https://github.com/ocpp-debugkit/ocpp-debugkit/security/advisories/new).
61+
62+
All complaints will be reviewed and investigated promptly and fairly.
63+
64+
All community leaders are obligated to respect the privacy and security of the
65+
reporter of any incident.
66+
67+
## Enforcement Guidelines
68+
69+
Community leaders will follow these Community Impact Guidelines in determining
70+
the consequences for any action they deem in violation of this Code of Conduct:
71+
72+
### 1. Correction
73+
74+
**Community Impact**: Use of inappropriate language or other behavior deemed
75+
unprofessional or unwelcome in the community.
76+
77+
**Consequence**: A private, written warning from community leaders, providing
78+
clarity around the nature of the violation and an explanation of why the
79+
behavior was inappropriate. A public apology may be requested.
80+
81+
### 2. Warning
82+
83+
**Community Impact**: A violation through a single incident or series of
84+
actions.
85+
86+
**Consequence**: A warning with consequences for continued behavior. No
87+
interaction with the people involved, including unsolicited interaction with
88+
those enforcing the Code of Conduct, for a specified period of time. This
89+
includes avoiding interactions in community spaces as well as external channels
90+
like social media. Violating these terms may lead to a temporary or permanent
91+
ban.
92+
93+
### 3. Temporary Ban
94+
95+
**Community Impact**: A serious violation of community standards, including
96+
sustained inappropriate behavior.
97+
98+
**Consequence**: A temporary ban from any sort of interaction or public
99+
communication with the community for a specified period of time. No public or
100+
private interaction with the people involved, including unsolicited
101+
interaction with those enforcing the Code of Conduct, is allowed during this
102+
period. Violating these terms may lead to a permanent ban.
103+
104+
### 4. Permanent Ban
105+
106+
**Community Impact**: Demonstrating a pattern of violation of community
107+
standards, including sustained inappropriate behavior, harassment of an
108+
individual, or aggression toward or disparagement of classes of individuals.
109+
110+
**Consequence**: A permanent ban from any sort of public interaction within the
111+
community.
112+
113+
## Attribution
114+
115+
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
116+
version 2.1, available at
117+
[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
118+
119+
Community Impact Guidelines were inspired by
120+
[Mozilla's code of conduct enforcement ladder][mozilla-coc].
121+
122+
For answers to common questions about this code of conduct, see the FAQ at
123+
[https://www.contributor-covenant.org/faq][faq]. Translations are available at
124+
[https://www.contributor-covenant.org/translations][translations].
125+
126+
[homepage]: https://www.contributor-covenant.org
127+
[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
128+
[mozilla-coc]: https://www.mozilla.org/en-US/about/governance/policies/enforcement/
129+
[faq]: https://www.contributor-covenant.org/faq
130+
[translations]: https://www.contributor-covenant.org/translations

‎CONTRIBUTING.md‎

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
# Contributing to OCPP DebugKit
2+
3+
Thank you for your interest in contributing to OCPP DebugKit! This document
4+
covers setup, conventions, and the contribution workflow.
5+
6+
## Getting Started
7+
8+
### Prerequisites
9+
10+
- **Node.js** >= 20.0.0
11+
- **pnpm** 10.x (`npm install -g pnpm`)
12+
- **Git**
13+
14+
### Local Setup
15+
16+
```bash
17+
# Clone the repository
18+
git clone https://github.com/ocpp-debugkit/ocpp-debugkit.git
19+
cd ocpp-debugkit
20+
21+
# Install dependencies
22+
pnpm install
23+
24+
# Verify everything works
25+
pnpm lint
26+
pnpm test
27+
pnpm build
28+
```
29+
30+
## Monorepo Structure
31+
32+
```
33+
ocpp-debugkit/
34+
├── packages/
35+
│ ├── core/ # Data model, parser, normalizer, timeline, failure detection
36+
│ ├── scenarios/ # Predefined trace scenarios for testing
37+
│ ├── reporter/ # Report generators (Markdown, HTML)
38+
│ ├── cli/ # Command-line interface
39+
│ ├── replay/ # Replay engine (v0.2+)
40+
│ └── react/ # Reusable React components (v0.2+)
41+
├── apps/
42+
│ └── web/ # Single Next.js app (landing, inspector, docs, blog)
43+
└── ...
44+
```
45+
46+
See [`AGENTS.md`](./AGENTS.md) for a detailed overview of the architecture,
47+
build commands, and package dependency graph.
48+
49+
## Development Workflow
50+
51+
### 1. Find or Create an Issue
52+
53+
All work should be tracked via GitHub Issues. Check existing issues or create
54+
a new one using the appropriate issue template (bug report, feature request,
55+
or scenario request).
56+
57+
### 2. Create a Branch
58+
59+
```bash
60+
git checkout -b feat/<scope>-<description>
61+
```
62+
63+
### 3. Make Your Changes
64+
65+
- Follow the code style (TypeScript strict, Prettier, ESLint).
66+
- Write tests for the behavior you introduce.
67+
- Update documentation as needed.
68+
69+
### 4. Verify Locally
70+
71+
```bash
72+
pnpm lint
73+
pnpm typecheck
74+
pnpm test
75+
pnpm build
76+
```
77+
78+
### 5. Add a Changeset
79+
80+
If your PR changes publishable package behavior, add a changeset:
81+
82+
```bash
83+
pnpm changeset
84+
```
85+
86+
This creates a file in `.changeset/` describing the change and which packages
87+
are affected.
88+
89+
### 6. Open a Pull Request
90+
91+
- Use the PR template.
92+
- Link the issue with `Closes #N`.
93+
- Ensure CI passes (lint, typecheck, test, build).
94+
95+
## Conventions
96+
97+
### Commit Messages
98+
99+
This project uses [Conventional Commits](https://www.conventionalcommits.org/):
100+
101+
```
102+
feat(core): implement trace parser for JSON input
103+
fix(cli): handle missing trace file gracefully
104+
docs: add architecture overview to docs
105+
chore: add vitest configuration
106+
test(core): add parser edge case tests
107+
```
108+
109+
### Branch Naming
110+
111+
```
112+
feat/<scope>-<description> # e.g. feat/core-parse-trace
113+
fix/<scope>-<description> # e.g. fix/cli-stdout-encoding
114+
chore/<description> # e.g. chore/ci-workflow
115+
docs/<description> # e.g. docs/readme
116+
test/<description> # e.g. test/core-coverage
117+
```
118+
119+
### Code Style
120+
121+
- **TypeScript strict mode** — no `any` without justification.
122+
- **Prettier** for formatting (single quotes, trailing commas, 100 char width).
123+
- **ESLint** with `typescript-eslint` strict rules.
124+
- Use `import type` for type-only imports.
125+
126+
### Testing
127+
128+
- Tests use **Vitest**.
129+
- Test files: `*.test.ts` / `*.spec.ts`.
130+
- Tests live next to the code they test.
131+
- Coverage target: 70%+ for core package.
132+
133+
## Security Guidelines
134+
135+
OCPP DebugKit processes untrusted input (trace files, pasted content). When
136+
working on parsing, CLI, or UI code:
137+
138+
- **Validate all external input** — CLI args, file content, paste input.
139+
- **Safe JSON parsing** — always use try/catch and enforce size limits.
140+
- **No dynamic code execution** — no `eval()`, `Function()` on untrusted input.
141+
- **No prototype pollution** — validate object shapes, use safe parsing.
142+
- **Path safety** — validate file paths, prevent path traversal.
143+
- **Safe rendering** — no `dangerouslySetInnerHTML`, no unsafe HTML injection.
144+
- **Browser-local processing** — no automatic uploading of user data.
145+
- **No secrets in committed files** — no credentials, API keys, or tokens.
146+
- **No sensitive data in committed artifacts** — use synthetic data in trace
147+
fixtures, sample data, and test data. Real station IDs, transaction IDs, IPs,
148+
or personal information must not appear in committed files. User-loaded
149+
traces and runtime-generated reports are **not** subject to this rule — they
150+
contain the user's own data and must not be redacted.
151+
152+
If you discover a security vulnerability, please see the
153+
[Security Policy](./SECURITY.md) for responsible disclosure.
154+
155+
## AI-Assisted Development
156+
157+
Maintainers may use AI-assisted development tools, but all contributions must
158+
be reviewed, tested, documented, and scoped like normal engineering work.
159+
AI-generated code is held to the same standards as any other contribution: it
160+
must pass CI, include tests, be security-reviewed, and be understandable by a
161+
human reviewer.
162+
163+
Contributors using AI agents can point them at [`AGENTS.md`](./AGENTS.md) for
164+
a structured overview of this repository's architecture, conventions, and build
165+
system. [`CURRENT_STATE.md`](./CURRENT_STATE.md) reflects what has been built
166+
so far and what is in progress — use it to orient your agent before starting
167+
work.
168+
169+
No AI tool preference is assumed or required. The project does not endorse any
170+
specific AI tool.
171+
172+
## Living Documents
173+
174+
The following documents are updated as part of the work, inside the PR:
175+
176+
| Document | When updated |
177+
|----------|-------------|
178+
| `CURRENT_STATE.md` | Inside every PR, before merge |
179+
| `AGENTS.md` | When architecture, packages, or build commands change |
180+
| `CONTRIBUTING.md` | When contribution process or conventions change |
181+
| `ROADMAP.md` | At each milestone boundary |
182+
| `README.md` | When description, badges, quickstart, or links change |
183+
184+
## Questions?
185+
186+
- Open a [GitHub Issue](https://github.com/ocpp-debugkit/ocpp-debugkit/issues)
187+
- Read the [documentation](https://ocppdebugkit.com/docs)
188+
- Check the [roadmap](./ROADMAP.md)

‎CURRENT_STATE.md‎

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ feature code lands.
2121
- ✅ GitHub labels created (type, package, priority, workflow)
2222
- ✅ 11 tracking issues created and assigned to M0 milestone
2323

24-
### Monorepo & Tooling (in progress — PR #12)
24+
### Monorepo & Tooling (PR #12)
2525
- ✅ Root `package.json` with pnpm workspace
2626
- ✅ `pnpm-workspace.yaml` (`packages/*`, `apps/*`)
2727
- ✅ `tsconfig.base.json` (strict TypeScript config)
@@ -32,21 +32,29 @@ feature code lands.
3232
- ✅ `NOTICE` file (Apache 2.0)
3333
- ✅ `AGENTS.md` + `CURRENT_STATE.md` (initial versions)
3434

35-
### CI & Release (in progress — this PR)
35+
### CI & Release (PR #13)
3636
- ✅ `.github/workflows/ci.yml` — lint, format check, typecheck, test, build on PR + push
3737
- ✅ `.github/workflows/release.yml` — Changesets version PR, npm publish, ecosystem tag + GitHub release
3838
- ✅ `.changeset/config.json` — public access, base branch main
3939

40-
### GitHub Templates (in progress — this PR)
40+
### GitHub Templates (PR #14)
4141
- ✅ `.github/PULL_REQUEST_TEMPLATE.md`
4242
- ✅ `.github/ISSUE_TEMPLATE/bug_report.md`
4343
- ✅ `.github/ISSUE_TEMPLATE/feature_request.md`
4444
- ✅ `.github/ISSUE_TEMPLATE/scenario_request.md`
4545

46+
### Community Docs (in progress — this PR)
47+
- ✅ `CONTRIBUTING.md` (setup, conventions, PR process, AI-assisted dev section)
48+
- ✅ `CODE_OF_CONDUCT.md` (Contributor Covenant 2.1)
49+
- ✅ `ROADMAP.md` (milestone summary)
50+
- ✅ `README.md` (description, badges, architecture, quickstart, support, links)
51+
- ✅ `SECURITY.md` (vulnerability reporting, security principles)
4652

53+
## What's Next
4754

48-
1. **PR4** (Issues #9–#11): CONTRIBUTING, CODE_OF_CONDUCT, ROADMAP, README
49-
2. **M0 complete** → proceed to M0.5 (Protocol & Trace-Format Design Phase)
55+
1. **M0 complete** → maintainer reviews and merges PRs #12–#15
56+
2. Add required status checks to branch protection (after CI runs on main)
57+
3. Proceed to M0.5 (Protocol & Trace-Format Design Phase)
5058

5159
## Known Blockers / Decisions Pending
5260

0 commit comments

Comments
 (0)