Skip to content

docs: improve README for community contribution#591

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
tomymaritano wants to merge 2 commits into
base:develop
Choose a base branch
from
Open

docs: improve README for community contribution #591

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d064959
docs: improve README for community contribution
cursoragent Aug 24, 2026
e7be690
Merge branch 'develop' into cursor/readme-community-contribution-1778
tomymaritano Aug 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 7 additions & 40 deletions .github/CONTRIBUTING.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -1,45 +1,12 @@
# Contributing to Dripnex

Thanks for your interest in contributing!
The contribution guide lives at the repository root:

## Getting Started
**[CONTRIBUTING.md](../CONTRIBUTING.md)**

1. Fork and clone the repo
2. Run `pnpm install` to install dependencies
3. Run `pnpm dev` to start the desktop app in dev mode
In short:

## Development

```bash
pnpm dev # Run desktop in dev mode
pnpm test # Run tests
pnpm typecheck # TypeScript validation
pnpm lint # ESLint
pnpm format # Prettier formatting
```

## Finding Issues

- Look for issues labeled [`good first issue`](https://github.com/dripnex/readide/labels/good%20first%20issue) for beginner-friendly tasks
- Issues labeled [`help wanted`](https://github.com/dripnex/readide/labels/help%20wanted) are open for community contributions

## Pull Requests

- Branch from `develop` (not `main`)
- Use conventional commits: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`
- Ensure `pnpm test` and `pnpm typecheck` pass
- Target `develop` branch for PRs

## Project Structure

```
apps/desktop/ # Electron app
apps/docs-site/ # VitePress documentation
apps/marketing-site/ # Astro marketing pages
packages/ # Shared packages (core, storage, plugins, etc.)
```

## Need Help?

- Open a [Discussion](https://github.com/dripnex/readide/discussions)
- Check the [Documentation](https://dripnex.github.io/readide/)
- Branch from `develop` and open PRs against `develop` (not `main`)
- Use conventional commits
- Run `pnpm test` and `pnpm typecheck`
- Plugins and themes belong in `dripnex/plugin-*` and `dripnex/theme-*` repositories, not this monorepo
113 changes: 76 additions & 37 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -1,52 +1,86 @@
# Contributing to Dripnex

Thank you for your interest in contributing to Dripnex!
Thank you for your interest in contributing.

## What Can I Contribute To?
This file is the contribution guide for **this repository** (`dripnex/app`). Plugins and themes belong in their own git repos — see below.

Dripnex uses an **Open Core** model:
## What you can contribute here

### Open Source (MIT) - Contributions Welcome!
Dripnex uses an **open-core** model, as documented in [LICENSE](./LICENSE).

| Package | Description |
### Open source (MIT)

The MIT packages listed in LICENSE. In this tree that includes:

| Path | Role |
| ------------------------- | --------------------------------- |
| `packages/core` | Markdown parsing, note operations |
| `packages/core` | Domain logic, markdown parsing |
| `packages/storage-core` | Storage interfaces |
| `packages/storage-sqlite` | SQLite implementation |
| `packages/storage-sqlite` | SQLite adapter |
| `packages/wikilinks` | Wikilink parsing |
| `packages/commands` | Command palette |
| `packages/embeds` | Image/embed handling |
| `packages/plugin-api` | Plugin API + theme system |
| `packages/commands` | Command palette logic |
| `packages/embeds` | Embed handling |
| `packages/plugin-api` | Plugin API and theme system |
| `packages/product-config` | Product configuration |

LICENSE also names `packages/tasks/`; that directory is not in the tree today.

### Proprietary — not open for contributions

- `apps/desktop` — desktop application
- `packages/licensing` — license validation

LICENSE also names `apps/marketing-site/`; marketing lives in a separate repo, not this monorepo.

### Plugins and themes — separate repositories

Do **not** add community plugins or themes to this monorepo.

Official packs are their own GitHub repositories under [github.com/dripnex](https://github.com/dripnex):

### Proprietary - Not Open for Contributions
- Plugins: `plugin-*` (for example [plugin-vim](https://github.com/dripnex/plugin-vim))
- Themes: `theme-*` (for example [theme-parchment](https://github.com/dripnex/theme-parchment))

- `apps/desktop` - The desktop application
- `packages/licensing` - License validation
To scaffold a local pack from this repo:

## How to Contribute
```bash
pnpm plugin init "My Plugin"
pnpm plugin init "Paper" --type theme
```

See [docs/plugins/](./docs/plugins/README.md) and [docs/PLUGIN_SYSTEM.md](./docs/PLUGIN_SYSTEM.md).

### 1. Fork and Clone
## How to contribute

### 1. Fork and clone

```bash
git clone https://github.com/YOUR_USERNAME/readide.git
cd readide
git clone https://github.com/YOUR_USERNAME/app.git
cd app
pnpm install
```

### 2. Create a Branch
Requirements: Node.js `>= 20` and pnpm `>= 9` (root `package.json`).

### 2. Branch from `develop`

```bash
git checkout develop
git pull origin develop
git checkout -b feat/your-feature
# or
git checkout -b fix/your-bugfix
```

### 3. Make Changes
The default branch is `develop`. Do not branch from `main` for product work.

### 3. Make changes

- Follow existing code style
- Add tests for new functionality
- Run `pnpm test` before committing
- Run `pnpm typecheck` to verify types
- Add tests for new functionality in MIT packages
- Run `pnpm test` and `pnpm typecheck` before committing

`pnpm test` excludes `@dripnex/storage-sqlite` (native module / Electron vs Node). That is expected.

### 4. Commit

Expand All@@ -58,36 +92,41 @@ fix: resolve bug
docs: update documentation
test: add tests
refactor: code cleanup
chore: maintenance
```

### 5. Submit PR
### 5. Open a pull request

- Open a Pull Request against `main`
- Describe your changes clearly
- Link any related issues
- Target **`develop`**, not `main`
- Describe the change and link related issues
- Use the [PR template](./.github/PULL_REQUEST_TEMPLATE.md)

## Development Setup
`main` is for production releases only.

## Development commands

```bash
pnpm install # Install dependencies
pnpm dev # Run desktop app in dev mode
pnpm test # Run tests
pnpm typecheck # Check TypeScript
pnpm dev # Turbo `dev` (desktop + any other package `dev` scripts)
pnpm --filter @dripnex/desktop dev # Desktop app only
pnpm test # Tests (excludes storage-sqlite)
pnpm typecheck # TypeScript
pnpm lint # ESLint
pnpm format # Prettier
pnpm build # Build all packages
```

More context: [README.md](./README.md).

## Code of Conduct

- Be respectful and inclusive
- Focus on constructive feedback
- Help others learn
See [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md).

## Questions?

- Open a [GitHub Discussion](https://github.com/dripnex/app/discussions)
- Check existing issues before creating new ones
- Check existing [issues](https://github.com/dripnex/app/issues) before opening a new one
- Security reports: [SECURITY.md](./SECURITY.md) (do not file a public issue)

## License

By contributing, you agree that your contributions will be licensed
under the MIT License (for open source packages).
By contributing to the MIT packages, you agree that your contributions are licensed under the MIT License, as stated in [LICENSE](./LICENSE).
114 changes: 86 additions & 28 deletions README.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -1,53 +1,111 @@
# Dripnex

Markdown-first, offline-forever desktop note app.
Markdown-first, offline-first desktop note app.

This repository is the **Dripnex desktop/product monorepo**: the Electron app plus shared TypeScript packages.

[![License: MIT](https://img.shields.io/badge/Core-MIT-green.svg)](./LICENSE)
[![Release](https://img.shields.io/github/v/release/dripnex/app)](https://github.com/dripnex/app/releases)

## About
## What this is

Dripnex stores notes as **standard Markdown files on disk**. The default is local and offline: the editor and your files do not require a network connection.

Plugins and themes are **not** shipped as extra trees inside this repo. Official packs live in their own GitHub repositories under [`github.com/dripnex`](https://github.com/dripnex), named `plugin-*` and `theme-*`.

### License (open core)

As documented in [LICENSE](./LICENSE):

This repository contains the **open-source core** of Dripnex. Core packages are licensed under MIT for community use and contributions. The desktop application and some commercial features remain proprietary.
- **MIT:** listed core packages (markdown/domain logic, storage interfaces, plugin API, and related libraries)
- **Proprietary:** `apps/desktop` (the desktop application) and `packages/licensing`

## Quick Start
See [LICENSE](./LICENSE) for the package list. Some other packages also declare MIT in their own `package.json`; treat LICENSE as the dual-license source of truth.

## How to run

**Requirements** (from root `package.json`): Node.js `>= 20` and pnpm `>= 9`. The repo pins `packageManager` to `pnpm@9.15.1`. CI currently uses Node 22.

```bash
# Clone
git clone https://github.com/dripnex/app.git
cd app

# Install
pnpm install

# Run
pnpm dev
```

## Open Source Packages
`pnpm dev` is `turbo dev`. It starts every workspace package that defines a `dev` script. Today that includes:

- `apps/desktop` — Electron app (`electron-vite dev`)
- `packages/api` — Wrangler (cloud API; not required to edit notes locally)
- `packages/mcp-server` — local MCP stdio server

To run **only** the desktop app:

```bash
pnpm --filter @dripnex/desktop dev
```

Other root scripts:

| Command | What it does |
| ---------------- | --------------------------------------------------------- |
| `pnpm test` | Tests, excluding `@dripnex/storage-sqlite` |
| `pnpm typecheck` | TypeScript across the workspace |
| `pnpm lint` | ESLint |
| `pnpm format` | Prettier |
| `pnpm build` | Production build via Turbo |

`pnpm test` skips `storage-sqlite` on purpose: that package's native `better-sqlite3` binary is built for Electron, not for a plain Node test run. CI runs those tests in a clean Node environment.

Native modules belong in `apps/desktop`. The desktop `postinstall` script runs `electron-builder install-app-deps`. Do not add native dependencies to workspace packages.

The default git branch is `develop`. Feature work branches from there, not from `main`.

| Package | Description |
| ------------------------- | ------------------------------ |
| `@dripnex/core` | Domain logic, markdown parsing |
| `@dripnex/storage-core` | Storage interfaces |
| `@dripnex/storage-sqlite` | SQLite implementation |
| `@dripnex/wikilinks` | Wikilink parsing |
| `@dripnex/commands` | Command palette |
| `@dripnex/embeds` | Image/embed handling |
| `@dripnex/plugin-api` | Plugin API + theme system |
## How to contribute

## Contributing
Read [CONTRIBUTING.md](./CONTRIBUTING.md) and the [Code of Conduct](./CODE_OF_CONDUCT.md).

See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
**Pull requests**

- Branch from `develop` (`feat/...` or `fix/...`).
- Open the PR against **`develop`**, not `main`. The [PR template](./.github/PULL_REQUEST_TEMPLATE.md) checks this.
- Use conventional commits (`feat:`, `fix:`, `docs:`, `test:`, `refactor:`, `chore:`).
- Run `pnpm test` and `pnpm typecheck` before you open the PR.

`main` is for production releases. Do not send product PRs there.

**What to change in this repo**

Contributions to the MIT packages listed in [LICENSE](./LICENSE) are welcome. `apps/desktop` and `packages/licensing` are proprietary.

**Plugins and themes**

Do not add community plugins or themes to this monorepo. Put them in their own git repo:

| Kind | Naming | Examples |
| ------ | ------------------- | ------------------------------------------------------------------------------------------------ |
| Plugin | `dripnex/plugin-*` | [plugin-vim](https://github.com/dripnex/plugin-vim), [plugin-mermaid](https://github.com/dripnex/plugin-mermaid), [plugin-math](https://github.com/dripnex/plugin-math), [plugin-stamp](https://github.com/dripnex/plugin-stamp) |
| Theme | `dripnex/theme-*` | [theme-parchment](https://github.com/dripnex/theme-parchment), [theme-harbor-dusk](https://github.com/dripnex/theme-harbor-dusk) |

Browse the org: [plugins](https://github.com/orgs/dripnex/repositories?q=plugin-), [themes](https://github.com/orgs/dripnex/repositories?q=theme-).

From this repo you can scaffold a local pack (`pnpm plugin init "My Plugin"` or `pnpm plugin init "Paper" --type theme`). Install/load details: [docs/plugins/](./docs/plugins/README.md) and [docs/PLUGIN_SYSTEM.md](./docs/PLUGIN_SYSTEM.md).

A few built-ins (for example tables) still live in the desktop app. That is separate from satellite `plugin-*` / `theme-*` repos.

## Layout

```
apps/desktop/ Electron app (main, preload, renderer) — proprietary
packages/ Shared libraries (MIT packages listed in LICENSE, plus others)
```

Workspace globs are `apps/desktop` and `packages/*` (`pnpm-workspace.yaml`). Marketing and the public docs site live in other repositories (`dripnex/marketing`, `dripnex/docs-site`), not here.

## Links

- [Website](https://dripnex.app)
- [Documentation](https://dripnex.app/docs)
- [Releases](https://github.com/dripnex/app/releases)

## License

- **Core packages:** MIT License
- **Desktop app:** Proprietary

See [LICENSE](./LICENSE) for details.
- [Issues](https://github.com/dripnex/app/issues)
- [Security](./SECURITY.md)
Loading