# Contributing to Illuscape

Thank you for helping make Inkscape more accessible to Illustrator migrants.

## How to add a keyboard shortcut

1. Open `config/keys/illustrator-cc.xml` and/or `config/keys/illustrator-cs6.xml`
2. Add a `<bind>` element:
   ```xml
   <bind key="KEY" action="INKSCAPE_ACTION" modifiers="Primary,Shift" />
   ```
   Valid modifiers: `Primary` (Ctrl/Cmd), `Shift`, `Alt`. Omit `modifiers=""` for bare keys.
3. Find Inkscape action names via `inkscape --action-list` on your system
4. Update the shortcut table in `README.md`
5. Update the shortcut comparison table in the spec if the shortcut differs between CC and CS6

## How to add a color palette

1. Create `config/palettes/YourPalette.gpl` following GPL format:
   ```
   GIMP Palette
   Name: Your Palette Name
   Columns: 8
   #
   255   0   0  Red
   ...
   ```
2. Add the filename to `uninstall.sh`'s `remove_files()` function so it gets cleaned up
3. The palette will be installed automatically by `install.sh` (it copies all `*.gpl` files)

## How to add a document template

1. Create an SVG at `config/templates/YourTemplate.svg`
2. Include a `sodipodi:namedview` element with appropriate canvas settings
3. Add the filename to `uninstall.sh`'s `remove_files()` function
4. The template will be installed automatically by `install.sh` (copies all `*.svg` files)

## How to add a preference

Preferences live in `config/preferences-patch.xml`. The XML merge algorithm (in
`scripts/merge_prefs.py`) does an upsert: it walks the patch tree, matches nodes
by their `id` attribute, and sets only the attributes present in the patch. It
never deletes nodes or attributes.

To add a new preference:
1. Find the relevant node in Inkscape's `preferences.xml` on a running install
2. Add the node/attribute to `config/preferences-patch.xml` with the correct `id` values
3. Write a test in `tests/test_merge_prefs.py` that verifies the attribute is set
4. Run `conda run -n cf python3 -m pytest tests/test_merge_prefs.py -v` to verify

## Running tests

```bash
# Python unit tests (merge algorithm)
conda run -n cf python3 -m pytest tests/test_merge_prefs.py -v

# Integration tests (requires bats-core)
bats tests/test_install.bats

# Validate all config files
conda run -n cf python3 -c "
from xml.etree import ElementTree as ET
from pathlib import Path
for f in [*Path('config/keys').glob('*.xml'), *Path('config/templates').glob('*.svg'),
          *Path('config/symbols').glob('*.svg'), Path('config/preferences-patch.xml')]:
    ET.parse(f)
    print(f'OK {f}')
"
```

## Commit format

```
feat: add <shortcut/palette/template>
fix: correct <behavior>
test: add test for <scenario>
docs: update <section>
```

## License

By contributing, you agree that your contributions are released under the MIT license.