CONTRIBUTING.md
No OneTemporary
Actions

Authored By

Unknown

Size

7 KB

Referenced Files

None

Subscribers

None

CONTRIBUTING.md
View Options

	# 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! 🎉

File Metadata

Mime Type: text/plain
Expires: Fri, Mar 20, 4:55 PM (1 d, 19 h)
Storage Engine: blob
Storage Format: Raw Data
Storage Handle: 19
Default Alt Text: CONTRIBUTING.md (7 KB)

CONTRIBUTING.mdNo OneTemporaryActions

CONTRIBUTING.mdView Options

File Metadata

Event Timeline

CONTRIBUTING.md
No OneTemporary
Actions

CONTRIBUTING.md
View Options