From 176f74235b240cce4ddb81c72a3f971cbc716c4f Mon Sep 17 00:00:00 2001 From: Brian Phillips <16819233+unipheas@users.noreply.github.com> Date: Thu, 23 Jul 2026 17:12:30 -0500 Subject: [PATCH] docs: welcome open-source contributors --- .github/ISSUE_TEMPLATE/bug_report.yml | 83 +++++++++++++++++++++ .github/ISSUE_TEMPLATE/config.yml | 5 ++ .github/ISSUE_TEMPLATE/feature_request.yml | 45 +++++++++++ .github/PULL_REQUEST_TEMPLATE.md | 25 +++++++ .gitignore | 8 ++ CONTRIBUTING.md | 87 ++++++++++++++++++++++ README.md | 29 +++++++- SECURITY.md | 41 ++++++++++ 8 files changed, 321 insertions(+), 2 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 CONTRIBUTING.md create mode 100644 SECURITY.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..2c31c97 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,83 @@ +name: Bug report +description: Report a reproducible problem with BarKeep +title: "[Bug]: " +labels: + - bug +body: + - type: markdown + attributes: + value: | + Thanks for helping improve BarKeep. Do not include passwords, tokens, + private notifications, calendar details, or signing credentials. + Security vulnerabilities should be reported privately. + - type: input + id: version + attributes: + label: BarKeep version + description: Shown at the bottom-right of the BarKeep menu. + placeholder: "1.0.13" + validations: + required: true + - type: dropdown + id: install + attributes: + label: Installation method + options: + - Homebrew cask + - GitHub release + - Built from source + validations: + required: true + - type: input + id: macos + attributes: + label: macOS version + placeholder: "macOS 15.5" + validations: + required: true + - type: input + id: firmware + attributes: + label: Busy Bar firmware version + placeholder: "1.0.2" + validations: + required: true + - type: dropdown + id: transport + attributes: + label: Connection + options: + - USB + - Wi-Fi + - Both + - Not device-related + validations: + required: true + - type: textarea + id: steps + attributes: + label: Steps to reproduce + description: Include the smallest reliable sequence that triggers the problem. + placeholder: | + 1. Open BarKeep + 2. Select… + 3. Observe… + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected behavior + validations: + required: true + - type: textarea + id: actual + attributes: + label: Actual behavior + validations: + required: true + - type: textarea + id: context + attributes: + label: Additional context + description: Add sanitized logs or screenshots if they help explain the issue. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..f1121f6 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: true +contact_links: + - name: Report a security vulnerability + url: https://github.com/unipheas/barkeep/security/advisories/new + about: Send sensitive security reports privately instead of opening an issue. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..3af2ab2 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,45 @@ +name: Feature request +description: Suggest a focused improvement to BarKeep +title: "[Feature]: " +labels: + - enhancement +body: + - type: textarea + id: problem + attributes: + label: Problem or opportunity + description: What workflow would this improve? + validations: + required: true + - type: textarea + id: proposal + attributes: + label: Proposed behavior + description: Describe what you would like BarKeep to do. + validations: + required: true + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + description: Share any workarounds or different approaches you considered. + - type: dropdown + id: area + attributes: + label: Area + options: + - Menu-bar app + - Busy Bar Arcade + - CLI + - MCP / AI integrations + - Homebrew packaging + - Documentation + - Other + validations: + required: true + - type: checkboxes + id: contribution + attributes: + label: Contribution + options: + - label: I may be willing to implement this in a pull request. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..11d407a --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,25 @@ +## Summary + +Describe what changed and why. + +## Verification + +- [ ] `swift test` +- [ ] `swift build -c release` +- [ ] Tested on a physical Busy Bar when the change affects device behavior + +## Device details + +- BarKeep version or branch: +- macOS version: +- Busy Bar firmware: +- Connection: USB / Wi-Fi / not applicable + +## Checklist + +- [ ] The change is focused and does not include unrelated files. +- [ ] Tests cover new or changed behavior. +- [ ] Public documentation is updated when setup or behavior changed. +- [ ] No passwords, tokens, private messages, signing credentials, or personal + data are included. +- [ ] UI changes include a screenshot or short recording. diff --git a/.gitignore b/.gitignore index 28cd5b7..abf8e7d 100644 --- a/.gitignore +++ b/.gitignore @@ -6,3 +6,11 @@ dist/ assets/AppIcon.iconset/ assets/preview.png PUBLISHING.md +.gstack/ +.env +.env.* +!.env.example +*.key +*.p12 +*.pem +*.mobileprovision diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..ca512f3 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,87 @@ +# Contributing to BarKeep + +Thanks for helping improve BarKeep. Bug reports, feature ideas, documentation +fixes, code contributions, and experimental forks are all welcome. + +## Ways to contribute + +- Open an issue for a reproducible bug or focused feature request. +- Improve documentation, setup instructions, or troubleshooting guidance. +- Add tests for device behavior and firmware edge cases. +- Submit a pull request for fixes or new features. +- Fork the project and adapt it for your own hardware or workflow. + +For a potential security vulnerability, do not open a public issue. Follow +[SECURITY.md](SECURITY.md) instead. + +## Development setup + +You need: + +- macOS 14 or newer +- Xcode command-line tools with Swift 5.9 or newer +- A Busy Bar for physical-device testing; the automated test suite does not + require one + +Fork the repository on GitHub, then clone your fork: + +```bash +git clone git@github.com:YOUR-USER/barkeep.git +cd barkeep +git remote add upstream https://github.com/unipheas/barkeep.git +git switch -c feature/your-change +``` + +Build and test: + +```bash +swift test +swift build +``` + +To assemble and launch the menu-bar app: + +```bash +./make-app.sh +``` + +The script uses an available Developer ID or Apple Development identity when +possible and otherwise falls back to ad-hoc signing. Locally signed builds may +need macOS privacy permissions granted again. + +## Pull requests + +Before opening a pull request: + +1. Rebase or merge the latest `upstream/main`. +2. Run `swift test` and `swift build -c release`. +3. Add or update tests for behavior changes. +4. Update the README or other public documentation when setup, behavior, or + user-facing features change. +5. Include screenshots for visible UI changes and note the Busy Bar firmware + version used for hardware testing. +6. Keep each pull request focused enough to review and revert independently. + +GitHub Actions runs the test suite and release build for every pull request. +Maintainers may ask for changes before merging. + +## Protect credentials and private data + +Never commit: + +- Busy Bar local HTTP API passwords or cloud API tokens +- Slack, GitHub, OpenAI, or other service tokens +- Apple app-specific passwords +- Signing certificates, private keys, provisioning profiles, or Keychain + exports +- Notification databases, logs, screenshots, or fixtures containing private + messages or calendar data + +Use placeholders in examples and environment variables for local CLI/MCP +configuration. If a credential is committed accidentally, revoke it +immediately and tell a maintainer through a private security report. + +## License + +By submitting a contribution, you agree that it may be distributed under +BarKeep's [MIT License](LICENSE). You retain copyright to your contribution. diff --git a/README.md b/README.md index 742bfc1..12e48e2 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,17 @@ # BarKeep 👾 +[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) +[![macOS 14+](https://img.shields.io/badge/macOS-14%2B-black.svg)](https://www.apple.com/macos/) +[![Latest release](https://img.shields.io/github/v/release/unipheas/barkeep)](https://github.com/unipheas/barkeep/releases/latest) + A macOS menu bar companion for the [Busy Bar](https://busy.app) — control your bar over USB or Wi-Fi, automate your busy status, and turn the little LED display into a proper developer peripheral. No cloud, no account, no telemetry: BarKeep talks directly to the bar's local HTTP API, either over USB (`http://10.0.4.20/api`, no authentication) or Wi-Fi (the bar's local IP address and local HTTP API password). +BarKeep is free and open-source software under the +[MIT License](LICENSE). You are welcome to use it, fork it, modify it, +redistribute it, or build your own project from it. Contributions are welcome. + ## Features **Menu bar app** (tabbed popover: Device / Message / Timers / Arcade / Settings) @@ -224,14 +232,31 @@ Verified against firmware 1.0.2 / API 24.3.0 ## Development ```bash +swift test # run the test suite swift build # debug build -./make-app.sh # release build + launch +./make-app.sh # signed release build + launch ``` The icon is generated: `cd assets && swift gen_icon.swift 1024 icon.png` (see `gen_icon.swift` for the pixel grid). +## Contributing + +Bug reports, feature ideas, documentation improvements, code contributions, +and personal forks are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the +development workflow and pull-request checklist. + +Please report potential vulnerabilities privately using +[GitHub's security advisory form](https://github.com/unipheas/barkeep/security/advisories/new); +see [SECURITY.md](SECURITY.md) for details. + ## License -MIT — see [LICENSE](LICENSE). +BarKeep is released under the [MIT License](LICENSE). In practical terms, you +may use, copy, modify, merge, publish, distribute, sublicense, and sell copies +of the software. Keep the copyright and license notice with copies or +substantial portions of the project. + +Contributions submitted to this repository are licensed under the same MIT +terms. Not affiliated with Busy Inc. Busy Bar is a product of https://busy.app. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..95ed872 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,41 @@ +# Security policy + +## Supported versions + +Security fixes are provided for the latest published BarKeep release. Upgrade +to the newest release before reporting a problem that may already be fixed. + +## Report a vulnerability privately + +Please use +[GitHub private vulnerability reporting](https://github.com/unipheas/barkeep/security/advisories/new). +Do not open a public issue for an undisclosed vulnerability. + +Include: + +- The affected BarKeep version and installation method +- Your macOS and Busy Bar firmware versions +- Reproduction steps or a proof of concept +- The expected security impact +- Any suggested mitigation + +Do not include real API passwords, OAuth tokens, signing credentials, private +notifications, or other personal data. Replace them with clearly marked test +values. + +You will receive a best-effort acknowledgement and follow-up through the +private advisory. Please allow time for a fix and coordinated disclosure +before publishing details. + +## Scope + +This policy covers code and release artifacts published by the +`unipheas/barkeep` and `unipheas/homebrew-barkeep` repositories. + +Busy Bar firmware, Busy cloud services, Slack, macOS, Homebrew, Claude, Codex, +and ChatGPT are third-party products. Report vulnerabilities in those products +to their respective maintainers unless BarKeep's code is the cause. + +Ordinary bugs, feature requests, and documentation corrections can be filed +through the public +[issue tracker](https://github.com/unipheas/barkeep/issues).