Skip to content

Commit 4af9d60

Browse files
jcouballjcouball
committed
docs: add contributing guidelines for PR workflow
- Add CONTRIBUTING.md with detailed development workflow
1 parent ddb9f46 commit 4af9d60

2 files changed

Lines changed: 289 additions & 2 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 281 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,281 @@
1+
# Contributing to MkDocs Snippet Lens
2+
3+
First, thank you for considering contributing to MkDocs Snippet Lens. This project is
4+
a community effort, and every contribution is valued.
5+
6+
This guide outlines the standards and procedures for contributing, from setting up your
7+
environment to submitting your changes. Please read it carefully to ensure your
8+
contributions can be merged smoothly.
9+
10+
- [TLDR](#tldr)
11+
- [Code of Conduct](#code-of-conduct)
12+
- [Getting Started](#getting-started)
13+
- [Development Environment Setup](#development-environment-setup)
14+
- [Prerequisites](#prerequisites)
15+
- [Install Dependencies and Tooling](#install-dependencies-and-tooling)
16+
- [Editor Setup (VS Code)](#editor-setup-vs-code)
17+
- [Development Workflow](#development-workflow)
18+
- [Main Command](#main-command)
19+
- [Other Useful Commands](#other-useful-commands)
20+
- [Testing \& Coverage](#testing--coverage)
21+
- [Coverage Requirement](#coverage-requirement)
22+
- [Running Tests Locally](#running-tests-locally)
23+
- [Adding Tests for New Code](#adding-tests-for-new-code)
24+
- [Common Patterns for Testability](#common-patterns-for-testability)
25+
- [Viewing Coverage Reports](#viewing-coverage-reports)
26+
- [Submitting Changes](#submitting-changes)
27+
- [Commit Message Format](#commit-message-format)
28+
- [Pull Request Process](#pull-request-process)
29+
- [Automation Pipeline](#automation-pipeline)
30+
31+
## TLDR
32+
33+
Here are the most important guidelines:
34+
35+
- **Prerequisites**: You must have Node.js (>= 20) and npm installed.
36+
- **One-Time Setup**: Run `npm ci` after cloning to install all development dependencies
37+
and Git hooks.
38+
- **Conventional Commits**: All commit messages must follow the Conventional Commits
39+
standard (e.g., `feat: ...`, `fix: ...`). A local Git hook will enforce this.
40+
- **Tests are Required**: All new features or bug fixes must include corresponding
41+
tests.
42+
- **Update Documentation**: Any change that impacts users (new features, settings, etc.)
43+
must be documented appropriately.
44+
- **Ensure CI passes locally**: Before submitting a pull request, run `npm run test:all`
45+
and ensure all checks (linting, testing, building) pass.
46+
- **Rebase Workflow**: Always work on a new branch. Your pull request must be rebased on
47+
the latest `main` branch before it will be merged with a fast-forward merge.
48+
49+
## Code of Conduct
50+
51+
This project and everyone participating in it is governed by our community standards.
52+
By participating, you are expected to uphold respectful and professional behavior.
53+
54+
## Getting Started
55+
56+
Before you begin, you'll need to fork and clone the repository.
57+
58+
1. Fork the repository on GitHub.
59+
60+
2. Clone your fork to your local machine:
61+
62+
```bash
63+
git clone https://github.com/YOUR_USERNAME/mkdocs-snippet-lens.git
64+
cd mkdocs-snippet-lens
65+
```
66+
67+
3. Add the upstream remote to keep your fork in sync:
68+
69+
```bash
70+
git remote add upstream https://github.com/main-branch/mkdocs-snippet-lens.git
71+
```
72+
73+
## Development Environment Setup
74+
75+
This project uses Node.js and TypeScript for the VS Code extension, with npm for
76+
dependency management and tooling.
77+
78+
### Prerequisites
79+
80+
You must have the following tools installed on your local machine:
81+
82+
- **Node.js**: Version 20.0.0 or newer.
83+
- **npm**: This is included with Node.js.
84+
- **Visual Studio Code**: For testing the extension.
85+
86+
### Install Dependencies and Tooling
87+
88+
Once you have the prerequisites, you can install all project dependencies and
89+
development tools by running:
90+
91+
```bash
92+
npm ci
93+
```
94+
95+
This command will:
96+
97+
1. Install all Node.js dependencies from the `package-lock.json` file.
98+
2. Run the `prepare` script in `package.json`, which uses Husky to set up the
99+
`commit-msg` Git hook (`.husky/commit-msg`).
100+
101+
The development tools (`eslint`, `typescript`, `mocha`, `c8`) are managed via
102+
`package.json` and invoked with npm scripts. You do not need to install them globally.
103+
104+
If you later pull changes that modify `package-lock.json`, re-run `npm ci` to keep
105+
local development tooling in sync.
106+
107+
### Editor Setup (VS Code)
108+
109+
For the best development experience, we recommend using VS Code with the following
110+
extensions:
111+
112+
- **ESLint**: `dbaeumer.vscode-eslint`
113+
- **TypeScript and JavaScript Language Features**: Built-in
114+
115+
This repository includes a `.vscode/settings.json` file that will automatically
116+
configure these extensions to use the project's rules.
117+
118+
## Development Workflow
119+
120+
The `package.json` scripts are the single source of truth for all common development
121+
tasks.
122+
123+
### Main Command
124+
125+
Before submitting a pull request, you must run the full test suite locally:
126+
127+
```bash
128+
npm run test:all
129+
```
130+
131+
This command runs unit tests and integration tests on your local machine. This is
132+
similar to what our GitHub workflow uses.
133+
134+
### Other Useful Commands
135+
136+
- `npm run lint` - Run ESLint to check code style
137+
- `npm run check-types` - Run TypeScript type checking
138+
- `npm run test:unit` - Run unit tests with coverage
139+
- `npm run test:integration` - Run integration tests in VS Code
140+
- `npm run compile` - Build the extension
141+
- `npm run watch` - Watch mode for development
142+
143+
## Testing & Coverage
144+
145+
This project enforces 100% statement coverage on business logic modules to maintain
146+
code quality and ensure all code paths are tested.
147+
148+
### Coverage Requirement
149+
150+
All contributions must maintain 100% statement coverage for business logic modules. The
151+
CI pipeline will automatically fail if coverage drops below this threshold.
152+
153+
Note: VS Code integration modules (`extension.ts`, `snippetLinkProvider.ts`,
154+
`snippetHoverProvider.ts`, `previewManager.ts`, `diagnosticManager.ts`) are excluded
155+
from coverage requirements as they are tested via integration tests.
156+
157+
### Running Tests Locally
158+
159+
```bash
160+
# Run unit tests with coverage
161+
npm run test:unit
162+
163+
# Run integration tests
164+
npm run test:integration
165+
166+
# Run all tests
167+
npm run test:all
168+
```
169+
170+
### Adding Tests for New Code
171+
172+
When adding new features or fixing bugs:
173+
174+
1. Write tests that cover all new code paths
175+
2. Run `npm run test:unit` to verify 100% coverage on business logic
176+
3. If coverage is below 100%, review the coverage report to identify uncovered lines
177+
4. Add tests for the uncovered statements
178+
179+
### Common Patterns for Testability
180+
181+
The codebase follows these patterns to enable testing:
182+
183+
- **Separate business logic from VS Code integration**: Business logic modules are in
184+
pure TypeScript functions that can be tested in isolation.
185+
- **Integration tests for VS Code features**: Features that require VS Code APIs are
186+
tested via integration tests that run in a real VS Code environment.
187+
188+
Example:
189+
190+
```typescript
191+
// Business logic (100% coverage required)
192+
export function createDiagnosticInfos(
193+
locations: SnippetLocation[],
194+
resolver: (path: string) => string | null
195+
): DiagnosticInfo[] {
196+
// Pure function - easily testable
197+
}
198+
199+
// VS Code integration (integration tests)
200+
export class DiagnosticManager {
201+
updateDiagnostics(document: vscode.TextDocument): void {
202+
// Uses VS Code APIs - tested via integration
203+
}
204+
}
205+
```
206+
207+
### Viewing Coverage Reports
208+
209+
After running `npm run test:unit`, you can view the coverage report:
210+
211+
1. Open `coverage/lcov-report/index.html` in your browser
212+
2. Click on individual files to see line-by-line coverage
213+
214+
## Submitting Changes
215+
216+
### Commit Message Format
217+
218+
This project uses Conventional Commits. This format is strictly enforced by a Git hook
219+
and our CI pipeline.
220+
221+
For the full specification and examples, see the
222+
[Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) website.
223+
224+
After running `npm ci`, a `commit-msg` hook is installed that automatically lints your
225+
commit message with `commitlint`.
226+
227+
- Your commit message must follow the format: `<type>(<scope>): <subject>`.
228+
- Allowed types are: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`,
229+
`build`, `ci`, `chore`, `revert`.
230+
- For details on all rules, see `.commitlintrc.yml`.
231+
232+
Examples:
233+
234+
- `feat(diagnostics): add error highlighting for missing files`
235+
- `fix: correct path resolution on Windows`
236+
- `docs: update installation instructions in README`
237+
238+
### Pull Request Process
239+
240+
1. Create a feature branch from the `main` branch.
241+
242+
2. Make your changes.
243+
244+
**Important Contributor Requirements**
245+
246+
- **All new code requires tests**: Any new feature or bug fix must be accompanied by
247+
corresponding tests.
248+
- **Documentation must be updated**: Any change that impacts user behavior (new
249+
commands, settings, etc.) must be documented in the `README.md`.
250+
251+
3. Ensure your code passes all local checks by running `npm run test:all`.
252+
253+
4. Rebase your branch on the latest `main`:
254+
255+
```bash
256+
git fetch upstream
257+
git rebase upstream/main
258+
```
259+
260+
If you encounter conflicts during the rebase, resolve them and continue:
261+
262+
```bash
263+
git add <files>
264+
git rebase --continue
265+
```
266+
267+
5. Push your branch and open a pull request against `main-branch/mkdocs-snippet-lens:main`.
268+
269+
6. Ensure all CI checks on the pull request pass.
270+
271+
## Automation Pipeline
272+
273+
We use a set of GitHub Actions to automate linting, testing, and quality checks.
274+
275+
- **Continuous Integration**: On every pull request,
276+
`.github/workflows/continuous-integration.yml` runs linting, type checking, unit
277+
tests, integration tests (on Ubuntu, macOS, and Windows), and builds the extension.
278+
- **Conventional Commits**: Commit messages are validated during CI to ensure they
279+
follow the Conventional Commits standard.
280+
- **100% Coverage**: The CI pipeline enforces 100% statement coverage on business logic
281+
modules.

‎README.md‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -41,8 +41,14 @@ issues.
4141

4242
## Contributing
4343

44-
Contributions are welcome! Please see the repository for development setup and
45-
guidelines.
44+
Contributions are welcome! Please read our
45+
[Contributing Guide](CONTRIBUTING.md) for details on our development workflow,
46+
including:
47+
48+
- Working on feature branches (never commit directly to `main`)
49+
- Creating and submitting pull requests
50+
- Rebase requirements for fast-forward merges
51+
- Code review process
4652

4753
## License
4854

0 commit comments

Comments
 (0)