Skip to content

Commit 2f1bae4

Browse files
BoxBoxJasonBoxBoxJason
committed
docs: add contributing guide
Signed-off-by: BoxBoxJason <contact@boxboxjason.dev>
1 parent 801265f commit 2f1bae4

2 files changed

Lines changed: 202 additions & 0 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
# Contributing
2+
3+
Thanks for taking the time to contribute!
4+
5+
This project follows an **issues-first** workflow:
6+
7+
- Please **create an issue first** for any change.
8+
- Please **only work on existing issues** (including documentation changes).
9+
- Contributions must come from a **fork** and be submitted as a **pull request** (merge request).
10+
11+
## Prerequisites
12+
13+
- VS Code
14+
- Node.js `24` (matches CI in [build workflow](.github/workflows/build.yml))
15+
- npm
16+
- Git
17+
18+
## Development setup
19+
20+
1. Fork the repository on GitHub.
21+
2. Clone your fork.
22+
3. Install dependencies:
23+
24+
- `npm ci`
25+
26+
4. Open the project in VS Code:
27+
28+
- `code .`
29+
30+
## Running the extension (local dev)
31+
32+
This repository is set up for the standard VS Code extension development workflow.
33+
34+
1. In VS Code, open the **Run and Debug** view.
35+
2. Select **Run Extension**.
36+
3. Press `F5`.
37+
38+
This launches an **Extension Development Host** window.
39+
40+
### Build/watch pipeline (what `F5` uses)
41+
42+
The debug launch uses the default VS Code task `watch` (see [.vscode/tasks.json](.vscode/tasks.json)). It runs:
43+
44+
- `npm run watch:esbuild` — bundles the extension entrypoint and the React webview bundle.
45+
- `npm run watch:tsc` — TypeScript type-check in watch mode (no emit).
46+
47+
If you prefer the command line, you can run those scripts directly in separate terminals.
48+
49+
## Tests
50+
51+
- Run tests once:
52+
- `npm test`
53+
54+
This compiles with `tsc` and runs extension tests via `@vscode/test-cli`/`@vscode/test-electron`.
55+
56+
- Run tests with coverage:
57+
- `npm run test:coverage`
58+
59+
This instruments the compiled output with `nyc`, runs the test runner, then produces reports.
60+
61+
## Linting & type checking
62+
63+
- Type-check:
64+
- `npm run check-types`
65+
66+
- Lint:
67+
- `npm run lint`
68+
69+
## Packaging (VSIX)
70+
71+
- Create a VSIX locally:
72+
- `npm run package`
73+
74+
This runs the production build and then packages via `vsce`.
75+
76+
## Script reference
77+
78+
These are the most useful scripts from [package.json](package.json):
79+
80+
- `npm run compile`
81+
- Cleans `dist/`, builds Tailwind CSS, and bundles the extension + webview via `esbuild`.
82+
83+
- `npm run build`
84+
- Production build: clean + Tailwind + typecheck + lint + minified bundle.
85+
86+
- `npm run watch:esbuild`
87+
- Watch-mode bundling for the extension and webview.
88+
89+
- `npm run watch:tsc`
90+
- Watch-mode typecheck (no output files are written).
91+
92+
- `npm test`
93+
- Compiles with `tsc` and runs the VS Code integration test runner.
94+
95+
- `npm run test:coverage`
96+
- Runs tests with `nyc` coverage.
97+
98+
- `npm run lint`
99+
- Lints `src/` using ESLint.
100+
101+
- `npm run check-types`
102+
- Runs `tsc --noEmit`.
103+
104+
- `npm run tailwind`
105+
- Builds the webview CSS from [src/views/style/main.css](src/views/style/main.css) into `dist/style/main.css`.
106+
107+
- `npm run clean`
108+
- Removes build/test artifacts (`dist`, `dist-cov`, `.nyc_output`).
109+
110+
- `npm run changelog`
111+
- Regenerates [CHANGELOG.md](CHANGELOG.md) via `git-cliff`.
112+
113+
## Workflow: issues first
114+
115+
1. **Open an issue**
116+
- Bug: include repro steps, expected vs actual behavior, and logs if possible.
117+
- Feature: explain the problem, the proposed change, and any privacy implications.
118+
119+
2. **Wait for confirmation**
120+
- A maintainer should confirm the issue is valid / wanted before you start work.
121+
122+
3. **Implement the change in your fork**
123+
- Create a topic branch from your fork’s `main`.
124+
- Keep PRs focused to the issue.
125+
126+
4. **Open a pull request (merge request)**
127+
- Reference the issue number (e.g. `Fixes #123`).
128+
- Describe what changed and how it was tested.
129+
130+
## Coding guidelines
131+
132+
- Keep changes scoped to the issue.
133+
- Avoid refactors in the same PR unless the issue explicitly calls for it.
134+
- Prefer maintaining existing style and patterns.
135+
- If you touch user-facing behavior, update docs if needed.
136+
137+
## Reporting bugs / requesting features
138+
139+
Please use the GitHub issue templates:
140+
141+
- Bug reports: [.github/ISSUE_TEMPLATE/bug_report.md](.github/ISSUE_TEMPLATE/bug_report.md)
142+
- Feature requests: [.github/ISSUE_TEMPLATE/feature_request.md](.github/ISSUE_TEMPLATE/feature_request.md)

‎README.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,10 @@ Achievements is a Visual Studio Code extension that allows you to track your pro
44

55
![Extension Webview Illustration](./screenshot.jpg)
66

7+
> [!WARNING]
8+
> This extension is in beta, may contain bugs and database schema may change in future versions.
9+
> It is recommended to back up your data before updating.
10+
711
## Features
812

913
- Track your progress in coding
@@ -17,6 +21,18 @@ Achievements is a Visual Studio Code extension that allows you to track your pro
1721
- Enable or disable notifications
1822
- Enable or disable any type of listeners for **privacy**
1923

24+
## How it works
25+
26+
- The extension activates on `onStartupFinished` and listens to VS Code and Git events (based on your settings).
27+
- Progress and achievement state are stored locally in a SQLite database powered by `sql.js` (no server).
28+
- The UI is a VS Code webview (React) opened via **Achievements: Show**.
29+
30+
### Local data & read-only mode
31+
32+
- Data is stored under VS Code's global storage as `achievements.sqlite`.
33+
- A lock prevents multiple VS Code instances from writing the database at the same time.
34+
- If another instance is using the DB, the extension runs in **read-only** mode: listeners are disabled and a status bar item indicates the state.
35+
2036
## Extension Commands
2137

2238
Several commands are available to interact with the Achievements extension. You can access these commands through the Command Palette (Ctrl+Shift+P) or by using keybindings.
@@ -49,6 +65,16 @@ You can also access the settings by using the command `achievements.settings`.
4965

5066
## Installation
5167

68+
### From OpenVSX
69+
70+
1. Download and install [Visual Studio Code](https://code.visualstudio.com/).
71+
2. Download and install the [Achievements Extension VSIX](https://open-vsx.org/extension/boxboxjason/achievements) from the OpenVSX registry.
72+
3. Open Visual Studio Code. Go to the Extensions view by clicking on the Extensions icon in the Activity Bar on the side of the window or by pressing `Ctrl+Shift+X`.
73+
4. Click on the three-dot menu icon in the top-right corner of the Extensions view and select "Install from VSIX...".
74+
5. In the file dialog that appears, navigate to the location where you downloaded the Achievements Extension VSIX file, select it, and click "Open".
75+
6. Visual Studio Code will install the extension. Once the installation is complete, you may need to reload Visual Studio Code for the extension to be activated. You can do this by clicking the "Reload" button that appears in the Extensions view after installation or by closing and reopening Visual Studio Code.
76+
7. Run the command `Achievements: Show` from the Command Palette (`Ctrl+Shift+P`) to open the Achievements panel.
77+
5278
### From VSIX
5379

5480
1. Download and install [Visual Studio Code](https://code.visualstudio.com/).
@@ -58,3 +84,37 @@ You can also access the settings by using the command `achievements.settings`.
5884
5. In the file dialog that appears, navigate to the location where you downloaded the Achievements Extension VSIX file, select it, and click "Open".
5985
6. Visual Studio Code will install the extension. Once the installation is complete, you may need to reload Visual Studio Code for the extension to be activated. You can do this by clicking the "Reload" button that appears in the Extensions view after installation or by closing and reopening Visual Studio Code.
6086
7. Run the command `Achievements: Show` from the Command Palette (`Ctrl+Shift+P`) to open the Achievements panel.
87+
88+
## Development
89+
90+
Prerequisites:
91+
92+
- Node.js `24` (matches CI)
93+
- npm
94+
- VS Code
95+
96+
Quick start:
97+
98+
1. Install dependencies: `npm ci`
99+
2. Open in VS Code: `code .`
100+
3. Press `F5` (launches the Extension Development Host)
101+
102+
Build system notes:
103+
104+
- The default debug launch runs the VS Code task `watch` (see [.vscode/tasks.json](.vscode/tasks.json)).
105+
- `watch:esbuild` bundles the extension + webview.
106+
- `watch:tsc` type-checks in watch mode.
107+
108+
Useful scripts:
109+
110+
|Command|Description|
111+
|---|---|
112+
|`npm run compile`|Clean + build Tailwind + bundle extension/webview (dev build)|
113+
|`npm run build`|Production build (typecheck + lint + minified bundle)|
114+
|`npm test`|Compile with `tsc` and run extension tests via `@vscode/test-cli`|
115+
|`npm run test:coverage`|Run tests with NYC coverage output|
116+
|`npm run lint`|Lint `src/`|
117+
|`npm run check-types`|Typecheck only (`tsc --noEmit`)|
118+
|`npm run package`|Build and create a `.vsix` via `vsce`|
119+
120+
Contributing guidelines: see [CONTRIBUTING.md](CONTRIBUTING.md).

0 commit comments

Comments
 (0)