diff --git a/CHANGELOG.md b/CHANGELOG.md index 795b17b5..bb141f09 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,12 @@ This project uses semantic versioning for public releases. Use `MAJOR.MINOR.PATC - `MINOR` changes add user-visible features and improvements. - `PATCH` changes fix bugs, polish existing behavior, or make small internal improvements. +## [Unreleased] + +### Added + +- A contributing guide (`CONTRIBUTING.md`) documenting how to build, test, and submit changes. + ## [1.2.1] - 2026-08-11 ### Improved diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..089bb0d0 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,117 @@ +# Contributing to FreeFlow + +Thanks for your interest in contributing to FreeFlow! FreeFlow is a free and open-source macOS dictation app, and community contributions are welcome. + +This guide describes how to set up the project, what conventions to follow, and how to submit your changes. + +## Prerequisites + +FreeFlow is a macOS app built with Swift and the macOS SDK. To build and test locally you need: + +- A Mac running macOS 13.0 or later +- Xcode Command Line Tools (`xcode-select --install`) +- [create-dmg](https://github.com/sindresorhus/create-dmg) (only needed for producing disk images) +- A free [Groq API key](https://groq.com/) (or another OpenAI-compatible provider) to exercise end-to-end dictation + +## Getting the Source + +1. Fork this repository on GitHub. +2. Clone your fork: + + ```bash + git clone https://github.com//freeflow.git + cd freeflow + git remote add upstream https://github.com/zachlatta/freeflow.git + ``` + +3. Keep your fork in sync with upstream before starting new work: + + ```bash + git fetch upstream + git checkout main + git merge upstream/main + git push origin main + ``` + +## Building + +```bash +make # builds FreeFlow.app into build/ +make run # builds and opens the app +``` + +The Makefile builds a `.app` bundle under `build/` using `swiftc` against the macOS SDK. It codesigns with a local "FreeFlow Dev" identity for development builds. + +To produce a universal (Apple Silicon + Intel) binary: + +```bash +make ARCH=universal +``` + +## Testing + +```bash +make test +``` + +The test runner is a standalone Swift executable built from `Sources/AppContextService.swift`, `Sources/LLMAPITransport.swift`, `Sources/ModelConfiguration.swift`, and `Tests/AppContextServiceTests.swift`. It runs without a simulator or test host. + +When adding features or fixing bugs, add or update tests in `Tests/` that cover the changed behavior. If your change touches code outside the currently tested files, extend the Makefile's `$(TEST_RUNNER)` target to include the new source files. + +## Development Conventions + +### Branches + +Create a branch from `main` for each change. Descriptive names are helpful, for example: + +- `feat/preserve-exact-wording` +- `fix/model-picker` +- `docs/contributing` + +### Commit Messages + +Write clear, concise commit messages in the imperative mood (e.g., "Add preserve-exact-wording toggle" rather than "Added preserve-exact-wording toggle"). There is no enforced commit-message format, but the existing history favors a short subject line optionally followed by a blank line and a body explaining the *why*. + +### Code Style + +- Swift code follows standard Swift formatting and naming conventions. +- Prefer small, focused changes that address a single issue or feature. +- Avoid unrelated refactors mixed into a feature or fix PR — if a refactor is needed, open a separate PR. + +### Changelog + +Add an entry under the `## [Unreleased]` section in [`CHANGELOG.md`](CHANGELOG.md) under the appropriate subsection: + +- **Added** — new user-visible features or improvements. +- **Improved** — enhancements to existing behavior. +- **Fixed** — bug fixes. + +Follow the existing entry style (one line per change, sentence case, no trailing period). + +## Submitting Changes + +1. Open a [pull request](https://github.com/zachlatta/freeflow/compare) against `zachlatta/freeflow:main`. +2. Include a description that covers: + - **Summary** — what the PR does, in a sentence or two. + - **Motivation** — why the change is needed (link the issue if one exists, e.g., `Closes #123`). + - **Behavior** — what changes for users, especially anything that differs from the previous behavior. + - **Changes** — the files touched and the nature of each change. + - **Test plan** — how you verified the change works (manual testing steps, `make test` output, edge cases checked). +3. Keep PRs focused and small. An automated labeler flags PRs over 1000 lines with a reminder that large PRs may be rejected — if your change is large, consider splitting it into multiple PRs. +4. A bot ([CodeRabbit](https://coderabbit.ai)) posts an automated review on new PRs. Addressing its actionable comments helps move the review forward. +5. Be responsive to feedback from maintainers and other contributors. + +## Reporting Issues + +- Search [existing issues](https://github.com/zachlatta/freeflow/issues) before opening a new one to avoid duplicates. +- Include the FreeFlow build number and macOS version (both are shown in the app's About or Settings window). +- Describe what you expected, what happened, and the steps to reproduce. +- Feature requests are welcome — label them as `enhancement` and explain the use case. + +## Discussions + +For ideas, questions, and show-and-tell that don't fit a specific issue, use [GitHub Discussions](https://github.com/zachlatta/freeflow/discussions). + +## License + +By contributing, you agree that your contributions are licensed under the [MIT license](LICENSE) that covers the project. \ No newline at end of file diff --git a/README.md b/README.md index f7d389d9..0247282f 100644 --- a/README.md +++ b/README.md @@ -109,6 +109,10 @@ defaults delete com.zachlatta.freeflow context_request_timeout_seconds +## Contributing + +See [CONTRIBUTING.md](CONTRIBUTING.md) for how to set up the project, build, test, and submit changes. + ## License Licensed under the MIT license.