Skip to content

Commit 4ca9764

Browse files
Redesign OverflowBar documentation
1 parent 960687f commit 4ca9764

15 files changed

Lines changed: 419 additions & 236 deletions

‎CONTRIBUTING.md‎

Lines changed: 17 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -1,53 +1,30 @@
1-
# Contributing to OverflowBar
1+
# Contributing
22

3-
Thanks for helping improve OverflowBar. Menu bar behavior varies by macOS version, display topology, and source application, so reproducible reports and focused changes are especially valuable.
3+
Menu-bar behavior varies by macOS release, display setup, and source application. Focused changes and reproducible reports help protect safe recovery.
44

5-
## Before opening an issue
5+
## Before filing a bug
66

7-
- Search existing issues.
8-
- Use **Settings → Safe Reset** to reveal the group.
9-
- Accessibility and Screen Recording are optional; use them only for discovery, activation, and previews.
10-
- Reproduce with the latest release.
7+
Search existing reports and reproduce on the latest release when possible. Include the macOS and OverflowBar versions, Mac and display setup, source app, expected and actual behavior, and exact steps. Remove private menu-bar or screen content from screenshots and logs.
118

12-
Bug reports should include the macOS version, Mac model/display setup, source app, expected behavior, actual behavior, and exact reproduction steps. Do not attach screenshots that expose private menu bar or screen content without reviewing them first.
9+
If icons are hidden unexpectedly, use **Settings → More → Reset Icon Selection**. Normal quit also reveals icons while preserving the saved selection.
1310

14-
## Development setup
11+
## Build and test
1512

16-
1. Use macOS 15 or later and Xcode 16 or later.
17-
2. Clone the repository.
18-
3. Open `OverflowBar.xcodeproj`.
19-
4. Build the `OverflowBar` scheme.
20-
5. Grant optional Accessibility or Screen Recording permission only when testing those features.
21-
22-
Command-line build:
23-
24-
```bash
25-
xcodebuild \
26-
-project OverflowBar.xcodeproj \
27-
-scheme OverflowBar \
28-
-configuration Debug \
29-
-destination 'platform=macOS' \
30-
CODE_SIGNING_ALLOWED=NO \
31-
build
32-
```
13+
Use macOS 15 or later and Xcode 26. Follow [Development](docs/DEVELOPMENT.md) for the project layout, Debug build, XCTest, helper tests, and native acceptance requirements.
3314

3415
## Pull requests
3516

36-
- Keep each pull request focused.
37-
- Explain user impact and the macOS versions tested.
38-
- Preserve the reveal-on-reset and reveal-on-quit paths; do not add synthetic input or cursor control.
39-
- Avoid private frameworks and any design that requires disabling platform security.
40-
- Add or update documentation for user-visible behavior.
41-
- Run `git diff --check` and both Debug and Release builds.
42-
43-
UI changes should respect Reduce Motion, safe areas, light/dark appearances, and small displays.
44-
45-
## Architecture
46-
47-
Read [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) before changing scanning, capture, divider geometry, or activation. Menu-bar placement changes across macOS releases; verify each supported version on live hardware.
17+
- Keep changes focused and explain user impact and macOS versions tested.
18+
- Preserve cancellation, timeouts, reveal-on-reset, and reveal-on-quit behavior.
19+
- Native operations may briefly move and restore the pointer; preserve bounded input and cleanup on every exit.
20+
- Avoid designs that require disabling System Integrity Protection. The current engine already uses private macOS APIs; treat them as a compatibility risk and preserve existing safeguards.
21+
- Document user-visible changes and keep third-party provenance and required license notices intact.
22+
- Run git diff --check, project builds, tests, and relevant validation checks before submitting.
4823

4924
## Security and privacy
5025

51-
Do not open a public issue for a vulnerability. Follow [SECURITY.md](SECURITY.md). Changes must preserve the local-only capture model documented in [PRIVACY.md](PRIVACY.md).
26+
Do not report vulnerabilities in a public issue. Follow [SECURITY.md](SECURITY.md). Preserve the local-only capture model in [Privacy](PRIVACY.md). Read the [architecture guide](docs/ARCHITECTURE.md) before changing discovery, capture, movement, or activation.
27+
28+
## Related guides
5229

53-
The v1.5 native engine uses pinned Ice/Thaw GPL code; preserve provenance and imported notices. Read [native validation](docs/NATIVE_VALIDATION.md) before claiming runtime reliability.
30+
[Development](docs/DEVELOPMENT.md) · [Architecture](docs/ARCHITECTURE.md) · [Privacy](PRIVACY.md) · [Security policy](SECURITY.md)

‎PRIVACY.md‎

Lines changed: 19 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,25 @@
11
# Privacy
22

3-
OverflowBar does not send icon captures, native menu information or layout selections to a server. Sparkle contacts the configured GitHub update feed to check signed updates.
3+
OverflowBar processes menu-bar layout and item captures locally. It does not send screen captures, menu contents, or layout selections to a server.
44

5-
Accessibility is used to attribute menu-bar controls and perform native arrangement/activation. Native mouse events and temporary pointer movement are permitted in v1.5. Operations are serialized, bounded and cleaned up on failure or cancellation.
5+
## Permissions and local processing
66

7-
Screen Recording is used for point-in-time captures of selected native status-item windows. Two authenticated local helper services isolate blocking discovery and capture. Captures remain in bounded memory; no screenshot history is recorded. The recyclable capture process confines the system private-capture leak.
7+
Accessibility identifies menu-bar controls and supports arrangement and activation. Native menu-bar operations can post mouse events and temporarily move and restore the pointer. Operations are bounded, cancellable, and cleaned up after failure.
88

9-
Permission denial is visible in setup/overview. Unknown native controls are not guessed or clicked. Private macOS APIs are used for compatibility with offscreen menu-bar windows and are a release-validation risk.
9+
Screen & System Audio Recording enables point-in-time captures of selected status-item windows. Captures stay in bounded memory, are not uploaded, and are not kept as screenshot history. The recyclable capture helper contains the system's private-capture leak.
1010

11-
Ad-hoc signing is retained. Updates can require macOS permission regranting. Only the installed build should be added to Privacy & Security; unrelated apps' grants remain untouched.
11+
Permission denial is shown in setup and settings. Unknown controls are not guessed or clicked. The app uses private macOS APIs to support off-screen menu-bar windows; operating-system changes can affect compatibility.
12+
13+
## Network access
14+
15+
Sparkle contacts the configured GitHub release feed to check for signed updates. The updater asks before installing. OverflowBar does not send captures or item choices with these checks.
16+
17+
## Signing and permission changes
18+
19+
Community builds are ad-hoc signed. Replacing a local build can require permission reauthorization. Remove only OverflowBar's stale permission entry; leave other applications' grants unchanged.
20+
21+
See [Permissions](docs/PERMISSIONS.md) for purpose, denial, and recovery details.
22+
23+
## Related guides
24+
25+
[Permissions](docs/PERMISSIONS.md) · [Installation](docs/INSTALLATION.md) · [Troubleshooting](docs/TROUBLESHOOTING.md)

‎README.md‎

Lines changed: 59 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,67 @@
1-
# OverflowBar
1+
<div align="center">
2+
<img src="assets/overflowbar-icon.png" alt="OverflowBar app icon" width="96" height="96" />
3+
<h1>OverflowBar</h1>
4+
<p><strong>Give your menu bar a second row.</strong></p>
5+
<p>Move the menu bar icons you choose into a second row, then open their original menus and popovers from one place.</p>
6+
<p><a href="https://github.com/EvanProgramming/OverflowBar/releases/latest">Download for macOS</a> · <a href="#quick-start">Quick start</a> · <a href="#documentation">Documentation</a></p>
7+
</div>
28

3-
OverflowBar v1.5 gives selected menu bar icons a second row. Open an icon there to use its original menu or popover.
9+
<p align="center">
10+
<a href="https://github.com/EvanProgramming/OverflowBar/releases/latest"><img src="https://img.shields.io/github/v/release/EvanProgramming/OverflowBar?display_name=tag&amp;color=333333" alt="Latest stable release" /></a>
11+
<a href="docs/INSTALLATION.md"><img src="https://img.shields.io/badge/macOS-15%20%26%2026-666666?logo=apple" alt="macOS 15 and 26 deployment targets" /></a>
12+
<a href="docs/INSTALLATION.md"><img src="https://img.shields.io/badge/Apple%20silicon%20%26%20Intel-universal-777777?logo=apple" alt="Universal Apple silicon and Intel build" /></a>
13+
<a href="LICENSE"><img src="https://img.shields.io/github/license/EvanProgramming/OverflowBar?color=555555" alt="GPL 3.0 license" /></a>
14+
</p>
415

5-
**v1.5.0 is the latest stable release**, with an updated native menu bar engine. Existing users can install it through the signed in-app updater or download the [release](https://github.com/EvanProgramming/OverflowBar/releases/tag/v1.5.0). The previous stable [v1.0.19 release](https://github.com/EvanProgramming/OverflowBar/releases/tag/v1.0.19) remains available as a manual fallback.
16+
<p align="center">
17+
<a href="docs/assets/second-row-open.png"><img src="docs/assets/second-row-open.png" alt="OverflowBar's second row open beneath the macOS menu bar" width="800" /></a>
18+
</p>
619

7-
- Choose menu bar icons one at a time.
8-
- Source-aware Tahoe discovery, including Control Center-hosted windows.
9-
- Authenticated ad-hoc discovery and recyclable capture helpers.
10-
- Open selected icons using Accessibility or supported menu bar actions.
11-
- A scrollable panel with system materials and keyboard accessibility.
12-
- Universal Intel/Apple Silicon build; macOS 15 target; macOS 27+ fails open.
13-
- Ad-hoc signing and signed Sparkle updates; no paid certificate required.
20+
The second row keeps selected menu bar controls available while leaving their original menu-bar position clear.
1421

15-
Accessibility is required to hide selected icons and open their menus. Screen Recording enables live previews. Moving icons may briefly move the pointer; you can cancel an operation at any time.
22+
**A clearer menu bar, without replacing your controls.** Choose which status icons to tuck away, open their real menus from the second row, and restore them whenever you like.
23+
24+
## Features
25+
26+
- **Choose icons individually.** Select the status items OverflowBar can arrange.
27+
- **Use the original controls.** Open source-app menus, popovers, and supported toggles.
28+
- **See live previews.** Screen Recording enables captured previews; app icons remain available without it.
29+
- **Use the keyboard and recover easily.** Navigate the panel, cancel an operation, reset the selection, or quit to reveal the icons.
30+
31+
## Installation
32+
33+
1. [Download the v1.5.0 DMG](https://github.com/EvanProgramming/OverflowBar/releases/download/v1.5.0/OverflowBar-1.5.0.dmg) or choose the [latest stable release](https://github.com/EvanProgramming/OverflowBar/releases/latest).
34+
2. Drag OverflowBar into Applications, then open it. The current DMG is named OverflowBar-1.5.0.dmg.
35+
3. Follow setup and select the icons you want in the second row.
36+
37+
If you prefer Homebrew, use the verified cask from this repository:
38+
39+
brew tap EvanProgramming/overflowbar https://github.com/EvanProgramming/OverflowBar.git
40+
brew install --cask EvanProgramming/overflowbar/overflowbar
41+
42+
The community build is ad-hoc signed and is not notarized. If macOS blocks an app you downloaded from the official release, follow Apple's [Open Anyway instructions](https://support.apple.com/guide/mac-help/open-a-mac-app-from-an-unknown-developer-mh40616/mac).
43+
44+
OverflowBar targets macOS 15 and has a universal Apple silicon and Intel build. The macOS 26.4 release check covered a limited native-fixture workflow; macOS 15 hardware and Intel hardware were not available for physical testing. On macOS 27 and later, native icon management fails open and leaves icons accessible. See [installation and compatibility](docs/INSTALLATION.md) and [release validation](docs/RELEASE_CHECKS_V1.5.md).
45+
46+
## Quick start
47+
48+
1. Enable **Accessibility** to arrange selected icons and open their controls.
49+
2. Optionally enable **Screen Recording** for live icon previews.
50+
3. In **Choose Icons**, select the status items to move.
51+
4. Select **Hide Icons & Finish**.
52+
5. Click **Open OverflowBar** in the menu bar, then choose an icon.
53+
54+
Turn off **Hide selected icons** to restore the selected icons. **Cancel** stops an active operation. **Reset Icon Selection** restores all icons and clears the selection; quitting reveals icons while keeping your saved choices.
1655

1756
## Documentation
1857

19-
[Installation](docs/INSTALLATION.md) · [Usage](docs/USAGE.md) · [Architecture](docs/ARCHITECTURE.md) · [Privacy](PRIVACY.md) · [Release process](docs/RELEASING.md) · [Contributing](CONTRIBUTING.md)
58+
- [Installation](docs/INSTALLATION.md) · [Using OverflowBar](docs/USAGE.md) · [Permissions](docs/PERMISSIONS.md)
59+
- [Troubleshooting and FAQ](docs/TROUBLESHOOTING.md) · [Homebrew](docs/HOMEBREW.md) · [Privacy](PRIVACY.md)
60+
- [Architecture](docs/ARCHITECTURE.md) · [Development](docs/DEVELOPMENT.md) · [Contributing](CONTRIBUTING.md)
61+
- [Documentation index and release evidence](docs/README.md)
62+
63+
## Contributing and license
64+
65+
See the [contributing guide](CONTRIBUTING.md) for development setup and issue reports. Report security issues privately using [GitHub’s security reporting page](https://github.com/EvanProgramming/OverflowBar/security/advisories/new). OverflowBar is distributed under the [GPL-3.0 license](LICENSE); earlier code retains its [original MIT notice](LICENSE-MIT-ORIGINAL). Native-engine provenance is documented in [third-party notices](THIRD_PARTY_NOTICES.md).
2066

21-
v1.5 adopts [GPL-3.0](LICENSE). Exact Ice/Thaw source pins and local changes are recorded in [third-party notices](THIRD_PARTY_NOTICES.md). Earlier OverflowBar code retains its [original MIT notice](LICENSE-MIT-ORIGINAL).
67+
The native engine incorporates portions of [Ice](https://github.com/jordanbaird/Ice) and [Thaw](https://github.com/thaw-app/Thaw); see the preserved [licenses and attribution](THIRD_PARTY_NOTICES.md).

0 commit comments

Comments
 (0)