Skip to content

Commit b06c677

Browse files
billybox1926-jpgbillybox1926-jpg
authored
Merge pull request #12 from saltines321-debug/issue-5-devex-standards
Add reusable DevEx standards and validation helpers
2 parents be9d24f + 1d7085f commit b06c677

5 files changed

Lines changed: 146 additions & 4 deletions

File tree

‎README.md‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ This template is intentionally generic so it can be adopted across teams, produc
1515
- **Scalable governance**: reusable conventions for labels, milestones, and releases.
1616
- **Production-grade defaults**: practical configuration for common Git and editor workflows.
1717
- **Modular architecture**: separate core logic, integrations, extensions, config, scripts, and tests.
18+
- **Reusable DevEx**: document setup, validation, debugging, dependency, and coding standards.
1819

1920
## Included components
2021

@@ -30,6 +31,7 @@ This template is intentionally generic so it can be adopted across teams, produc
3031
- Standards and governance documentation:
3132
- `docs/REPOSITORY_STANDARDS.md`
3233
- `docs/ARCHITECTURE.md`
34+
- `docs/DEVEX.md`
3335
- Modular template structure:
3436
- `core/`
3537
- `providers/`
@@ -48,7 +50,8 @@ This template is intentionally generic so it can be adopted across teams, produc
4850
2. Rename the repository and update project-specific fields.
4951
3. Confirm or replace `LICENSE` for your legal requirements.
5052
4. Update contacts in `SECURITY.md`, `CODEOWNERS`, and template placeholders.
51-
5. Enable branch protection and required status checks.
53+
5. Review `docs/DEVEX.md` and copy `config/.env.example` if runtime configuration is needed.
54+
6. Enable branch protection and required status checks.
5255

5356
## Recommended repository settings
5457

@@ -74,9 +77,14 @@ See `docs/REPOSITORY_STANDARDS.md` for reusable naming and governance convention
7477

7578
See `docs/ARCHITECTURE.md` for the reusable modular layout, including core/provider/plugin/config/test separation.
7679

80+
## Developer experience
81+
82+
See `docs/DEVEX.md` for local workflow, environment examples, dependency standards, validation, debugging, error handling, and coding standards.
83+
7784
## Suggested next steps
7885

7986
- Review prebuilt GitHub Actions workflows in `.github/workflows/` and enable commands for your stack.
87+
- Run or adapt `bash scripts/validate.sh` for local project validation.
8088
- Add language/tool-specific linting, formatting, and tests as your project grows.
8189
- Fill in the modular folders with project-specific implementation code.
8290
- Add project-specific architecture and operations documentation in `docs/`.
@@ -94,7 +102,11 @@ core/
94102
providers/
95103
plugins/
96104
config/
105+
.env.example
97106
docs/
107+
ARCHITECTURE.md
108+
DEVEX.md
109+
REPOSITORY_STANDARDS.md
98110
scripts/
99111
tests/
100112
CHANGELOG.md
@@ -110,4 +122,5 @@ SECURITY.md
110122
- CI entry workflow: `.github/workflows/ci.yml`
111123
- Release automation workflow: `.github/workflows/release.yml`
112124
- Bootstrap script: `scripts/bootstrap.sh`
125+
- Validation script: `scripts/validate.sh`
113126
- Developer setup guide: `docs/developer-setup.md`

‎config/.env.example‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Copy this file to your local environment file if the project needs runtime configuration.
2+
# Keep real secrets out of Git.
3+
4+
APP_ENV=development
5+
LOG_LEVEL=info
6+
7+
# Example placeholder values only. Replace locally as needed.
8+
EXAMPLE_API_URL=https://example.local
9+
EXAMPLE_API_KEY=YOUR_API_KEY_HERE

‎docs/DEVEX.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
# Developer Experience Standards
2+
3+
This document defines lightweight DevEx conventions for repositories created from this template.
4+
5+
The goal is a low-friction contributor workflow that remains portable across languages, frameworks, and project sizes.
6+
7+
## Local workflow
8+
9+
Recommended contributor loop:
10+
11+
1. Read `README.md` for project purpose and layout.
12+
2. Run `bash scripts/bootstrap.sh` to install or validate local prerequisites.
13+
3. Copy `config/.env.example` to a local environment file if the project needs environment variables.
14+
4. Make a focused change on a short-lived branch.
15+
5. Run `bash scripts/validate.sh` before opening a pull request.
16+
6. Open a PR with validation notes and any relevant screenshots or logs.
17+
18+
## Environment files
19+
20+
Keep examples safe and explicit:
21+
22+
- Commit `.env.example` files with placeholders only.
23+
- Never commit real secrets, tokens, credentials, private keys, or local machine paths.
24+
- Document required variables near the code or config that consumes them.
25+
- Prefer clear placeholder values such as `YOUR_API_KEY_HERE` or `example.local`.
26+
27+
## Dependency management
28+
29+
Each project should document its package manager and lockfile policy.
30+
31+
Recommended defaults:
32+
33+
- Applications should commit lockfiles when the ecosystem supports them.
34+
- Libraries and reusable templates may omit lockfiles unless reproducible installs require them.
35+
- Keep runtime dependencies small and justified.
36+
- Prefer standard tooling before adding extra packages.
37+
- Update dependencies intentionally and include validation notes in PRs.
38+
39+
## Validation standards
40+
41+
Template repositories should support these task names when applicable:
42+
43+
- `format:check` for formatting validation
44+
- `lint` for static analysis
45+
- `test` for automated tests
46+
47+
The reusable GitHub Actions workflow can call custom commands for each project. Local validation should stay simple and safe to run repeatedly.
48+
49+
## Debugging workflow
50+
51+
When something fails:
52+
53+
1. Reproduce the issue from a clean checkout if possible.
54+
2. Capture the exact command, expected result, and actual result.
55+
3. Check environment variables and local config against `config/.env.example`.
56+
4. Run the smallest relevant validation command first.
57+
5. Add notes to the issue or PR explaining what was verified.
58+
59+
Avoid committing temporary debug output, machine-specific paths, or local credentials.
60+
61+
## Error handling conventions
62+
63+
Prefer errors that are actionable:
64+
65+
- Say what failed.
66+
- Say what input or config caused the failure when safe.
67+
- Suggest the next command or config field to check.
68+
- Avoid hiding errors with broad catch-all handling.
69+
- Do not print secrets or sensitive values in logs.
70+
71+
## Coding standards
72+
73+
General coding expectations:
74+
75+
- Keep changes focused and easy to review.
76+
- Favor clear names over clever abstractions.
77+
- Keep core logic separate from provider or plugin code.
78+
- Add tests for behavior, not implementation trivia.
79+
- Update docs when behavior, setup, or architecture changes.
80+
- Prefer small modules with obvious ownership.
81+
82+
## Pull request hygiene
83+
84+
A healthy PR should include:
85+
86+
- a clear summary
87+
- linked issues when applicable
88+
- validation steps
89+
- screenshots or logs when useful
90+
- documentation updates for user-facing or contributor-facing changes

‎docs/developer-setup.md‎

Lines changed: 17 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
This guide provides generic onboarding defaults intended for template-based repositories.
44

5+
For broader contributor workflow, dependency, debugging, validation, and coding standards, see `docs/DEVEX.md`.
6+
57
## 1) Prerequisites
68

79
- Git 2.40+
@@ -19,6 +21,8 @@ bash scripts/bootstrap.sh
1921

2022
If your repository is not Node.js based, adapt `scripts/bootstrap.sh` to your stack and keep command names consistent with CI.
2123

24+
If the project needs runtime configuration, copy `config/.env.example` to your local environment file and replace placeholder values locally.
25+
2226
## 3) Recommended task contract
2327

2428
To keep automation portable, define task commands with predictable names:
@@ -29,7 +33,17 @@ To keep automation portable, define task commands with predictable names:
2933

3034
This template's reusable workflow can call any shell command, but these names improve discoverability.
3135

32-
## 4) CI customization
36+
## 4) Local validation
37+
38+
Run the reusable validation helper before opening a PR:
39+
40+
```bash
41+
bash scripts/validate.sh
42+
```
43+
44+
Adapt this script as the project adopts a specific language stack.
45+
46+
## 5) CI customization
3347

3448
The repository ships with:
3549

@@ -54,14 +68,14 @@ with:
5468
test-command: npm test
5569
```
5670
57-
## 5) Branch and PR workflow
71+
## 6) Branch and PR workflow
5872
5973
1. Create a branch from `main`.
6074
2. Run local validation commands before opening a PR.
6175
3. Open a focused PR and include context for reviewers.
6276
4. Merge only when CI checks pass.
6377

64-
## 6) Lightweight automation standards
78+
## 7) Lightweight automation standards
6579

6680
- Keep workflows minimal and composable.
6781
- Prefer reusable workflows over duplicated YAML.

‎scripts/validate.sh‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
#!/usr/bin/env bash
2+
set -euo pipefail
3+
4+
if [[ -f package.json ]]; then
5+
if command -v npm >/dev/null 2>&1; then
6+
npm run format:check --if-present
7+
npm run lint --if-present
8+
npm test --if-present
9+
else
10+
echo "npm is not installed; skipping Node validation."
11+
fi
12+
else
13+
echo "No package.json found; add project-specific validation commands here as the template is adopted."
14+
fi
15+
16+
echo "Validation complete."

0 commit comments

Comments
 (0)