Skip to content

Commit 9509b08

Browse files
fry69bartlomiejuclaude
authored
docs: add contributing section (#3384)
Adds a Contributing section to the Fresh documentation covering: - Repository structure and package layout - Getting started (clone, `deno task ok`) - Development workflow (docs site, vite demo, `links` for external projects) - Testing (commands, conventions, known local issues) Single page at `docs/latest/contributing/index.md`. --------- Co-authored-by: Bartek Iwańczuk <biwanczuk@gmail.com> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 1accb21 commit 9509b08

2 files changed

Lines changed: 97 additions & 0 deletions

File tree

docs/latest/contributing/index.md

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
---
2+
description: |
3+
Guidelines and resources for contributing to Fresh.
4+
---
5+
6+
# Contributing
7+
8+
Fresh is organized as a monorepo with multiple packages:
9+
10+
- **`packages/fresh/`** - Core Fresh framework (`@fresh/core`)
11+
- **`packages/plugin-vite/`** - Vite integration plugin (`@fresh/plugin-vite`)
12+
- **`packages/plugin-tailwindcss/`** - Tailwind CSS v4 plugin
13+
- **`packages/plugin-tailwindcss-v3/`** - Tailwind CSS v3 plugin
14+
- **`packages/init/`** - Project scaffolding tool
15+
- **`packages/update/`** - Fresh update utilities
16+
- **`www/`** - Documentation website (fresh.deno.dev)
17+
18+
## Getting Started
19+
20+
Prerequisites: [Deno](https://deno.com/) (latest version) and Git.
21+
22+
```sh Terminal
23+
git clone https://github.com/denoland/fresh.git
24+
cd fresh
25+
deno task ok
26+
```
27+
28+
`deno task ok` runs formatting, linting, type checking, and the full test suite.
29+
Run it before submitting any pull request.
30+
31+
The repository uses Deno
32+
[workspaces](https://docs.deno.com/runtime/fundamentals/workspaces/) so all
33+
packages in `packages/` are automatically available to each other using their
34+
published names (`@fresh/core`, `@fresh/plugin-vite`, etc.).
35+
36+
## Development
37+
38+
The `www/` directory and the Vite plugin demo both use local Fresh packages,
39+
making them good integration tests:
40+
41+
```sh Terminal
42+
deno task www # docs site dev server
43+
deno task build-www # docs site production build
44+
45+
deno task demo # vite demo dev server
46+
deno task demo:build # vite demo production build
47+
deno task demo:start # serve vite demo production build
48+
```
49+
50+
### Testing in External Projects
51+
52+
To use your local Fresh checkout in a separate project, add
53+
[`links`](https://docs.deno.com/runtime/fundamentals/configuration/#links) to
54+
the project's `deno.json`:
55+
56+
```json deno.json
57+
{
58+
"imports": {
59+
"@fresh/core": "jsr:@fresh/core@^2.0.0",
60+
"@fresh/plugin-vite": "jsr:@fresh/plugin-vite@^1.0.0"
61+
},
62+
"links": [
63+
"../path/to/fresh/packages/fresh",
64+
"../path/to/fresh/packages/plugin-vite"
65+
]
66+
}
67+
```
68+
69+
This overrides the JSR packages with your local versions. Changes are reflected
70+
immediately without rebuilding.
71+
72+
## Testing
73+
74+
```sh Terminal
75+
# All tests (parallel)
76+
deno task test
77+
78+
# A specific test file
79+
deno test -A packages/fresh/src/app_test.ts
80+
81+
# Filter by test name
82+
deno test -A --filter "test name pattern"
83+
84+
# Update snapshots after intentional output changes
85+
deno test -A --update-snapshots path/to/test.ts
86+
```
87+
88+
Tests use `@std/expect` for assertions, follow the `*_test.ts` naming
89+
convention, and require the `-A` flag. Snapshot tests are stored in
90+
`__snapshots__/` directories.
91+
92+
Some tests may fail locally but pass in CI (`Could not find server address`,
93+
`Text file busy (os error 26)`) — these can be safely ignored.

docs/toc.ts

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -103,6 +103,10 @@ const toc: RawTableOfContents = {
103103
["session-management", "Session management", "link:latest"],
104104
],
105105
},
106+
contributing: {
107+
title: "Contributing",
108+
link: "latest",
109+
},
106110
},
107111
},
108112
"1.x": {

0 commit comments

Comments
 (0)