> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/pret/pokeemerald/llms.txt
> Use this file to discover all available pages before exploring further.

# Contribution Guidelines

> How to contribute to pokeemerald.

pokeemerald is a community decompilation effort. The primary goal is accuracy: every line of C code must compile to machine code that is byte-identical to the original ROM. Contributions that change game behavior are only accepted when explicitly labeled as a bugfix or intentional feature addition.

## Community

<CardGroup cols={2}>
  <Card title="pret Discord" icon="discord" href="https://discord.gg/d5dubZ3">
    The main hub for decompilation discussion, review coordination, and contributor support. You must join before opening a PR.
  </Card>

  <Card title="IRC" icon="message-square">
    IRC is also available for contributors who prefer it. Ask in Discord for current channel details.
  </Card>
</CardGroup>

<Note>
  All contributors are required to join the [pret Discord](https://discord.gg/d5dubZ3) and include their Discord username in every pull request.
</Note>

## Pull request requirements

Every PR must use the provided template and include two things:

* **Description** — a clear summary of what changed and why.
* **Discord contact info** — your username (e.g. `pikalaxalt`) or legacy username#numbers format (e.g. `PikalaxALT#5823`).

PRs missing either field will not be reviewed until they are filled in.

## The matching requirement

<Warning>
  Any change that is not explicitly a bugfix or new feature **must not alter game behavior**. The compiled ROM must be byte-identical to the original. Run `make compare` before opening a PR to verify this.
</Warning>

```bash theme={null}
make compare
```

`make compare` builds the ROM and compares it against the known-good SHA-1 hash:

```
sha1: f3ae088181bf583e55daf962a92bb46f4f1d07b7
```

If the comparison fails, the change is not yet matching and cannot be merged as-is.

## How to contribute

<Steps>
  <Step title="Fork the repository">
    Fork [pokeemerald on GitHub](https://github.com/pret/pokeemerald) and clone your fork locally. Follow [INSTALL.md](https://github.com/pret/pokeemerald/blob/master/INSTALL.md) to set up the build environment, including the agbcc toolchain.
  </Step>

  <Step title="Create a branch">
    Create a dedicated branch for your changes. Use a descriptive name that reflects the scope of the work (e.g. `decompile-battle-anim-util` or `fix-berry-crush-score`).

    ```bash theme={null}
    git checkout -b decompile-my-function
    ```
  </Step>

  <Step title="Make your changes and verify">
    Make your changes, then run `make compare` to confirm the ROM is still byte-identical to the original.

    ```bash theme={null}
    make compare
    ```

    The build must succeed and the comparison must pass before you proceed.
  </Step>

  <Step title="Open a pull request">
    Push your branch and open a PR against `pret/pokeemerald`. Fill in the PR template completely:

    * Describe exactly what you changed and how you verified matching.
    * Include your Discord username so reviewers can reach you.
  </Step>

  <Step title="Participate in review">
    Join the [pret Discord](https://discord.gg/d5dubZ3) and follow the `#pokeemerald` channel. Reviewers may ask you to adjust your code to achieve a better match or improve readability. Respond promptly to keep the review moving.
  </Step>
</Steps>

## Welcomed contributions

<AccordionGroup>
  <Accordion title="Decompiling remaining asm stubs">
    Many functions still exist only as assembly stubs under `asm/`. Replacing them with equivalent, matching C code is the core ongoing work of the project. See [Decompilation Standards](/contributing/decompilation-standards) for matching requirements.
  </Accordion>

  <Accordion title="Fixing matching issues">
    Some already-decompiled functions have known non-matching details — minor differences in register allocation or instruction scheduling. Fixes that bring these closer to the original ROM are always welcome.
  </Accordion>

  <Accordion title="Documentation">
    Improving comments, naming previously anonymous structs or fields, and writing documentation for this site all help future contributors understand the codebase faster.
  </Accordion>

  <Accordion title="Tooling improvements">
    Scripts, Makefiles, and build tooling improvements that do not change the ROM output are generally accepted. Discuss large changes in Discord first.
  </Accordion>
</AccordionGroup>

## Changes that require prior discussion

<Warning>
  Do not open a PR for any of the following without first discussing it in the pret Discord:
</Warning>

* **Behavior changes** — any modification that causes `make compare` to fail and is not an agreed-upon bugfix.
* **Refactoring** — renaming, restructuring, or reformatting existing code in a way that breaks `make compare`.
* **New features** — adding gameplay content or mechanics not present in the original ROM.

Bring these proposals to `#pokeemerald` on Discord so the team can evaluate them before you invest time in implementation.