ignis/CONTRIBUTING.md

# Contributing to Ignis

Thanks for your interest in contributing. Here are some ways you can help.

## Reporting Plugin Compatibility Issues

Testing plugins and reporting what works (or doesn't) is one of the most valuable contributions right now. When a plugin doesn't work, the browser console usually contains the information needed to diagnose the problem.

### How to file a useful compatibility report

1. Open the browser dev tools (F12 or Ctrl+Shift+I)
2. Go to the **Console** tab
3. Enable the plugin or trigger the failing action
4. Look for errors, especially lines starting with:
   - `[ignis] Unshimmed require: <module>` - a Node.js module the plugin needs that Ignis doesn't provide yet
   - `[shim:MISS] <module>.<property>` - a property or method on a shimmed module that isn't implemented
   - `Plugin failure: <plugin-id>` - Obsidian caught a crash from the plugin
5. Copy the full error including the stack trace

### What to include in the issue

- Plugin name and version
- What you tried to do
- What happened (error, crash, nothing, partial functionality)
- The console output (errors and shim warnings)
- Whether the plugin loads at all or fails immediately

### Example of a useful report

> **Plugin:** Templater v1.18.4
> **Status:** Broken on load
>
> Console shows:
> ```
> [ignis] Unshimmed require: util
> [shim:MISS] UNKNOWN(util).promisify - property not found on shim
> Plugin failure: templater-obsidian TypeError: t is not a function
> ```
>
> The plugin needs `util.promisify` which isn't shimmed yet.

This kind of report makes it straightforward to add the missing shim.

## Code Contributions

If you want to contribute code:

1. Fork the repo and create a branch for your change
2. Run `npm install` once at the repo root (npm workspaces)
3. Run `npm run dev` to build and start the server
4. Test your change in the browser with at least one vault open
5. Run `npm test` and make sure the whole suite passes
6. Keep PRs focused - one fix or feature per PR

Changes to deliberate behavior (the fs shim's caching and write model, the proxy's request handling, anything documented as a design decision) start as an issue, not a PR. Open the issue first so the approach can be discussed; a patch against an undiscussed design change will be closed on this basis.

### Project structure

- `packages/shim/` - Browser shims for Node.js and Electron APIs
- `packages/ui/` - Svelte UI components (vault manager, dialogs)
- `packages/bridge/` - The ignis-bridge Obsidian plugin (settings, file actions)
- `packages/server-core/` - Shared server helpers (path guards, watcher, WebSocket)
- `apps/ignis-server/` - Express server, Docker image, demo mode
- `apps/ignis-server/server/plugins/` - Server plugin packages (e.g., headless-sync)

See [ARCHITECTURE.md](docs/ARCHITECTURE.md) for more detail.

### Adding a new shim

If a plugin needs a Node.js module that isn't shimmed:

1. Create the shim in `packages/shim/src/node/<module>.js`
2. Export the functions the plugin needs (stub what you can't implement)
3. Register it in `packages/shim/src/require.js` (import + add to `rawRegistry`)
4. Build and test with the plugin that needed it