# Contributing to Neoboard Miro Converter

Thank you for your interest in contributing to the Neoboard Miro Converter project! We welcome contributions from the community.

## Mailing List Workflow vs Merge Requests

This project uses a **mailing list-based workflow** similar to the Linux kernel and Git project itself, rather than pull/merge requests on platforms like GitHub or GitLab.

**Why mailing lists?**

- Contributions are reviewed via email using patch files
- Discussion happens on the mailing list, accessible to everyone
- No need for a centralized platform account
- Follows the battle-tested workflow used by major open source projects

If you're coming from a merge request workflow, don't worry! This guide will walk you through the process step by step.

## Getting Started

### 1. Clone the repository

```bash
git clone https://git.midnightthoughts.space/neoboard-miro-converter
cd neoboard-miro-converter
```

### 2. Create a topic branch for your changes

Just like creating a branch for a merge request, create a branch for your feature or fix:

```sh
git checkout -b my-feature-branch
```

Use a descriptive branch name like `fix-export-bug` or `add-dark-mode-support`.

### 3. Make your changes

Make your changes and commit them with clear, descriptive commit messages:

```sh
git add .
git commit -m "Short summary of changes (50 chars or less)

More detailed explanation of what changed and why. Wrap lines at 72
characters. This is similar to a merge request description, but it goes
in your commit message instead.

- You can use bullet points
- To highlight specific changes
- Or important details"
```

**Commit Message Best Practices:**

- First line: Brief summary (imperative mood: "Add feature" not "Added feature")
- Blank line
- Detailed explanation of what and why (not how - the code shows how)
- Reference any related issues or discussions

### 4. Generate patches with `git format-patch`

This is where the workflow differs from merge requests. Instead of pushing to a remote and opening a PR/MR, you create patch files:

**For a single commit:**

```sh
git format-patch -1 -s
```

**For multiple commits (e.g., last 3 commits):**

```sh
git format-patch -3 -s
```

**For all commits on your branch (compared to main):**

```sh
git format-patch -s origin/main
```

**What do these flags mean?**

- `-s` or `--signoff`: Adds a "Signed-off-by" line to your patch, certifying you have the right to submit this code
- `-n` or `--numbered`: Adds `[PATCH 1/N]` numbering to patches (automatic when multiple patches)

After running this command, you'll see files like:

```text
0001-Fix-export-bug-with-special-characters.patch
0002-Add-tests-for-export-functionality.patch
```

### 5. Create a cover letter (for multi-patch series)

When submitting multiple related patches, add a cover letter to explain the overall goal:

```sh
git format-patch -s --cover-letter origin/main
```

This creates an additional file: `0000-cover-letter.patch`

**Edit the cover letter** to include:

- A clear subject line describing the overall change
- A summary of what the patch series accomplishes
- Why these changes are needed
- How they're implemented (high-level overview)
- Testing done
- Any areas where you'd like specific feedback

**Example cover letter:**

```text
Subject: [PATCH 0/3] Improve export handling for special characters

This patch series improves how the exporter handles special characters
in board names and content.

The first patch fixes a bug where certain Unicode characters would cause
exports to fail. The second patch adds comprehensive test coverage for
various character encodings. The third patch updates documentation to
reflect the new capabilities.

Testing:
- Tested with boards containing emoji, CJK characters, and special symbols
- All existing tests pass
- Added 15 new test cases

I'm particularly interested in feedback on the encoding approach used in
patch 1.
```

### 6. Review your patches

Before sending, review your patches:

```sh
git format-patch -s --stdout origin/main | less
```

Or open the `.patch` files in your editor to ensure:

- Commit messages are clear and well-formatted
- Changes are logical and well-organized
- No unintended changes are included

### 7. Submit your patchset to the mailing list

Send your patches to: `neoboard-miro-converter@lists.midnightthoughts.space`

**Using `git send-email` (recommended):**

First, configure git to use your email:

```sh
git config --global sendemail.smtpserver smtp.example.com
git config --global sendemail.smtpserverport 587
git config --global sendemail.smtpencryption tls
git config --global sendemail.smtpuser your-email@example.com
```

Then send your patches:

```sh
git send-email --to=neoboard-miro-converter@lists.midnightthoughts.space *.patch
```

**Using your email client (alternative):**

If you prefer to use your regular email client:

1. Attach all `.patch` files to your email (including the cover letter if present)
2. Send to: `neoboard-miro-converter@lists.midnightthoughts.space`
3. Use a clear subject line if sending a single patch, or "Patch series: [your description]" for multiple patches
4. In the email body, include any additional context or questions

**Important notes:**

- Keep patches as attachments or inline (don't zip them)
- Send all patches of a series in a single email thread (they should thread automatically with `git send-email`)
- Be patient - maintainers will review and respond via the mailing list

### 8. Respond to feedback

When maintainers or other contributors reply to your patches:

- Respond on the mailing list (reply-all to keep everyone in the loop)
- Address concerns and questions
- If changes are requested, make them and send a new version

**Sending a revised version:**

```sh
# Make your changes
git add .
git commit --amend  # Or create new commits and squash them

# Generate v2 patches
git format-patch -s -v2 origin/main
```

This creates patches labeled `[PATCH v2 1/N]`. In your cover letter or email, note what changed between versions:

```text
Changes in v2:
- Fixed memory leak pointed out by Jane
- Renamed function as suggested by John
- Added error handling for edge case
```

## Additional Guidelines

### Code Quality

- Ensure your code follows the project's coding standards
- Run existing tests and ensure they pass
- Write tests for new features or bug fixes
- Keep commits focused - one logical change per commit

### Commit Organization

- Split large changes into a series of smaller, logical commits
- Each commit should build cleanly and pass tests
- This makes review easier and git history more useful

### Documentation

- Update documentation for any user-facing changes
- Add code comments for complex logic
- Update the README if you add new features

### Communication

- Be respectful and constructive in all communications
- Remember that text can be misinterpreted - assume good intent
- If something is unclear, ask questions!

## Useful Resources

- [Git format-patch documentation](https://git-scm.com/docs/git-format-patch)
- [Git send-email documentation](https://git-scm.com/docs/git-send-email)
- [Linux kernel patch submission guidelines](https://www.kernel.org/doc/html/latest/process/submitting-patches.html)

## Questions?

If you have questions about the contribution process, feel free to ask on the mailing list: `neoboard-miro-converter@lists.midnightthoughts.space`

Thank you for your contributions to the Neoboard Miro Converter project! 🎉