# Contributing to Gina

Gina follows a BDFL governance model — see [GOVERNANCE.md](./GOVERNANCE.md) for how decisions are made. Contributions of all experience levels are welcome.

---

## Table of contents

- [Requirements](#requirements)
- [Getting started locally](#getting-started-locally)
- [Running the tests](#running-the-tests)
- [Development environment](#development-environment)
- [Debugging](#debugging)
- [Coding conventions](#coding-conventions)
- [Branch model](#branch-model)
- [Local git hooks (opt-in)](#local-git-hooks-opt-in)
- [Commit style](#commit-style)
- [Changelog](#changelog)
- [Pull request checklist](#pull-request-checklist)
- [Reporting bugs](#reporting-bugs)
- [Proposing features](#proposing-features)

---

## Requirements

| Requirement | Version |
| --- | --- |
| OS | macOS or Linux (Windows: Docker only) |
| Node.js | >= 18 |
| npm | >= 8 |
| Changie | >= 1.24 |

---

## Getting started locally

Gina must be installed globally — the CLI and framework bootstrapper expect to run from the npm global prefix. Contributors clone directly into that location instead of using `npm install -g .`.

#### 1. Find your global prefix

```bash
npm config get prefix --quiet
```

The default is `/usr/local` (system) or `~/.npm-global` (user). The target directory is `${prefix}/lib/node_modules/gina`.

#### 2. Clone into the prefix

```bash
cd $(npm config get prefix)/lib/node_modules
git clone https://github.com/gina-io/gina.git gina
cd gina && git checkout develop
```

#### 3. Run the install scripts

```bash
node ./script/pre_install.js
node ./script/post_install.js
```

#### 4. Verify

```bash
gina version
```

---

## Running the tests

The test suite uses Node's built-in `node:test` runner — no additional test dependencies needed.

```bash
# Run all tests
node --test test/**/*.test.js framework/v*/test/unit/*.test.js

# Run a single file
node --test test/core/controller.test.js
```

---

## Development environment

When contributing to the framework, use the `dev` environment. It enables hot-reload, the debug toolbar, and verbose logging that makes it easier to follow what the framework is doing internally.

```bash
gina framework:set --env=dev
```

This sets the default environment so you can omit `--env=dev` from subsequent commands. To start the framework:

```bash
gina start
```

To follow logs in real time:

```bash
gina tail --follow
```

To revert to production defaults:

```bash
gina framework:set --env=prod
```

---

## Debugging

### Framework

```bash
gina start --inspect-gina
```

### Bundle

```bash
gina bundle:restart <bundle_name> @<project_name> --inspect=<port_number>
```

---

## Coding conventions

All coding conventions — variable declarations, function style, constructor patterns, error handling, async patterns, naming, JSDoc, EventEmitter usage, path handling, logging, and test conventions — are documented in [CONVENTIONS.md](./CONVENTIONS.md).

Please read it before submitting your first pull request.

---

## Branch model

| Branch | Purpose |
| --- | --- |
| `master` | Stable — merged from `develop` via PR at release time |
| `develop` | Working branch — all PRs target this branch |

Always branch from `develop` and open your PR against `develop`.

---

## Local git hooks (opt-in)

If you have multiple git identities on one machine (work, personal, internal hostname), it is easy to commit under the wrong `user.email` and leak a private domain into the public git log. This repo ships an opt-in `pre-commit` hook that refuses commits authored under a private-domain identity.

Install it once from the repo root:

```bash
cp resources/git-hooks/pre-commit .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit
```

The hook checks `git config user.email` against a short list of private-domain patterns (see the `BLOCKED_PATTERNS` regex inside `resources/git-hooks/pre-commit` for the current list) and exits with an error message if any match — letting you switch identity (`git config user.email you@public-domain.example`) before retrying.

Edit `resources/git-hooks/pre-commit` and extend the `BLOCKED_PATTERNS` regex to cover any additional private domain or hostname suffix you want to guard against. The hook is local to your clone — it is not shared across contributors, so each contributor installs it independently.

---

## Commit style

Use imperative or gerund sentences, matching the existing log:

```text
Fixed GlobalContext::whisper() memory leak
Added _debugLog to server.isaac.js
Allowing bundle:build to build for dev env
```

- One logical change per commit
- No references to AI tools in commit messages, comments, or files

---

## Changelog

Gina uses [changie](https://changie.dev) for changelog management. After any user-facing change, run:

```bash
changie new
```

Pick the kind (`Added`, `Changed`, `Fixed`, `Removed`, `Security`) and write the body from the user's perspective. Do **not** edit `CHANGELOG.md` directly — changie generates it at release time from entries in `.changes/unreleased/`.

---

## Pull request checklist

Before opening a PR against `develop`:

- [ ] Tests pass — `node --test test/**/*.test.js framework/v*/test/unit/*.test.js`
- [ ] New behaviour is covered by a test (or an explanation is provided for why it cannot be)
- [ ] A `changie new` entry exists for any user-facing change
- [ ] Commit messages follow the style above
- [ ] Docs updated if public API, CLI, or config schema changed (see [gina-io/docs/CONTRIBUTING.md](https://github.com/gina-io/docs/blob/main/CONTRIBUTING.md))

---

## Reporting bugs

Open a [GitHub issue](https://github.com/gina-io/gina/issues) and include:

- Node.js version (`node --version`)
- Gina version (`gina --version`)
- Minimal reproduction steps
- Expected vs actual behaviour

---

## Proposing features

Open a GitHub issue describing the use case **before** writing code. Features that align with the [roadmap](./ROADMAP.md) and architecture are most likely to be accepted. Significant API changes go through a public discussion period before being finalised.

---

## Maintainers

| Name | Role | Profile |
| --- | --- | --- |
| Martin Luther | Lead maintainer | [rhinostone.com](https://rhinostone.com) |
| Fabrice DELANEAU | Co-author | [fdelaneau.com](https://fdelaneau.com) |
