Skip to content

Commit f83e521

Browse files
sozercansozercan
committed
docs: add user-facing README and contributor guide
Signed-off-by: Sertac Ozercan <sozercan@gmail.com>
1 parent eed514a commit f83e521

2 files changed

Lines changed: 75 additions & 39 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# Contributing to OpenInCode
2+
3+
## Development requirements
4+
5+
- macOS 12 or newer
6+
- Swift 6.2 or newer
7+
- Xcode 26 or newer for the `actool` step that compiles the current Icon Composer asset
8+
- Visual Studio Code or Visual Studio Code Insiders for end-to-end testing
9+
10+
OpenInCode uses Swift Package Manager and Apple frameworks only; there are no external package dependencies.
11+
12+
## Build and test
13+
14+
Clone the repository, then build the SwiftPM executable and run the focused tests:
15+
16+
```sh
17+
swift build
18+
./scripts/test.sh
19+
```
20+
21+
`./scripts/test.sh` is the canonical test command. It runs the Swift tests with warnings treated as errors and validates the generated Homebrew cask.
22+
23+
## Build the app bundle
24+
25+
Assemble an unsigned Release app for verification:
26+
27+
```sh
28+
OPEN_IN_CODE_SIGNING=unsigned ./scripts/build-app.sh release
29+
```
30+
31+
The app is written to `.build/app/Open in Code.app`.
32+
33+
The packaging script applies an ad-hoc signature by default so Finder automation entitlements are available during local development. Set `OPEN_IN_CODE_SIGNING=unsigned` to skip signing. Set `ARCHES="arm64 x86_64"` when a universal app is required.
34+
35+
To try the local build:
36+
37+
1. Copy `.build/app/Open in Code.app` to `/Applications`.
38+
2. Hold Command and drag the app from `/Applications` to a Finder toolbar.
39+
3. Click the toolbar icon while viewing a folder or selecting a file.
40+
41+
## Publishing a release
42+
43+
Pushing a `v*` tag runs `.github/workflows/release.yml`. The workflow builds a universal app, signs it, creates a GitHub release, and updates `Casks/open-in-code.rb` in [`sozercan/homebrew-repo`](https://github.com/sozercan/homebrew-repo).
44+
45+
Public releases require all of these GitHub Actions secrets:
46+
47+
- `HOMEBREW_REPO_SSH_KEY`: the private half of a write-enabled deploy key for `sozercan/homebrew-repo`
48+
- `MACOS_CERTIFICATE`, `MACOS_CERTIFICATE_PWD`, `MACOS_KEYCHAIN_PWD`: a Developer ID Application PKCS#12 and its temporary keychain credentials
49+
- `APPLE_ID`, `APPLE_APP_SPECIFIC_PASSWORD`, `APPLE_TEAM_ID`: notarization credentials
50+
51+
Tag pushes and manual runs with `publish=true` fail unless Developer ID signing and notarization succeed. A manual run with `publish=false` may use ad-hoc signing for validation, but it never creates a GitHub release or updates Homebrew. Prerelease tags create GitHub prereleases but do not replace the stable Homebrew cask.
52+
53+
Do not create tags, publish releases, notarize artifacts, update the Homebrew tap, or change signing identities, team IDs, bundle identifiers, or release secrets as part of a normal contribution.

‎README.md‎

Lines changed: 22 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1,66 +1,49 @@
11
# OpenInCode
22

3-
Finder toolbar app that opens the current Finder folder—or the folder containing the selected file—in Visual Studio Code.
4-
5-
OpenInCode prefers stable Visual Studio Code and falls back to Visual Studio Code Insiders when stable is not installed.
3+
Open the folder you are viewing in Finder—or the folder containing a selected item—in Visual Studio Code with one toolbar click.
64

75
## Requirements
86

97
- macOS 12 or newer
108
- Visual Studio Code or Visual Studio Code Insiders
11-
- Swift 6.2 or newer
12-
- Xcode 26 or newer for the `actool` step that compiles the current Icon Composer asset
139

1410
## Install
1511

16-
Install the latest release from the Homebrew tap:
12+
Install the latest release with Homebrew:
1713

1814
```sh
1915
brew install --cask sozercan/repo/open-in-code
2016
```
2117

22-
Release archives are also available from the [GitHub Releases](https://github.com/sozercan/OpenInCode/releases) page.
18+
You can also download the app from [GitHub Releases](https://github.com/sozercan/OpenInCode/releases). If you download it directly, move **Open in Code.app** to `/Applications`.
2319

24-
To build from source:
20+
## Add Open in Code to Finder
2521

26-
1. Clone this repository.
27-
2. Run `./scripts/build-app.sh release`. The script uses SwiftPM and creates `.build/app/Open in Code.app`.
28-
3. Copy `Open in Code.app` to `/Applications`.
29-
4. Hold Command and drag the app from `/Applications` to a Finder toolbar.
30-
5. Click the toolbar icon while viewing a folder or selecting a file.
22+
1. Open `/Applications` in Finder.
23+
2. Hold Command and drag **Open in Code** to the Finder toolbar.
24+
3. Release it where you want the toolbar button to appear.
3125

32-
The first use asks for permission to control Finder. If permission was denied, enable **Open in Code → Finder** here:
26+
To remove or reposition the button later, hold Command while dragging it.
3327

34-
- macOS 13 or newer: **System Settings → Privacy & Security → Automation**
35-
- macOS 12: **System Preferences → Security & Privacy → Privacy → Automation**
28+
## Use
3629

37-
The local packaging script applies an ad-hoc signature by default so Finder automation entitlements are available during development. Public release artifacts should be signed with a Developer ID Application certificate and notarized before distribution.
30+
Open a Finder window, optionally select an item, and click **Open in Code** in the toolbar.
3831

39-
## Development
32+
- A selected folder opens directly.
33+
- A selected file or Finder package opens its containing folder.
34+
- If multiple items are selected, the first item is used.
35+
- If nothing is selected, the folder shown in the front Finder window opens.
36+
- Visual Studio Code is preferred; Visual Studio Code Insiders is used when the stable app is not installed.
4037

41-
Build the SwiftPM executable and run the focused path and editor-selection tests:
38+
## Allow Finder access
4239

43-
```sh
44-
swift build
45-
./scripts/test.sh
46-
```
40+
On first use, macOS asks whether **Open in Code** may control Finder. Allow access so the app can read the current Finder selection.
4741

48-
Assemble an unsigned Release app bundle for verification:
42+
If access was previously denied, enable **Open in Code → Finder** here:
4943

50-
```sh
51-
OPEN_IN_CODE_SIGNING=unsigned ./scripts/build-app.sh release
52-
```
53-
54-
Set `ARCHES="arm64 x86_64"` when a universal app is required.
55-
56-
## Publishing a release
57-
58-
Pushing a `v*` tag runs `.github/workflows/release.yml`. The workflow builds a universal app, signs it, creates a GitHub release, and updates `Casks/open-in-code.rb` in [`sozercan/homebrew-repo`](https://github.com/sozercan/homebrew-repo).
59-
60-
Public releases require all of these Actions secrets:
44+
- macOS 13 or newer: **System Settings → Privacy & Security → Automation**
45+
- macOS 12: **System Preferences → Security & Privacy → Privacy → Automation**
6146

62-
- `HOMEBREW_REPO_SSH_KEY`: the private half of a write-enabled deploy key for `sozercan/homebrew-repo`
63-
- `MACOS_CERTIFICATE`, `MACOS_CERTIFICATE_PWD`, `MACOS_KEYCHAIN_PWD`: a Developer ID Application PKCS#12 and its temporary keychain credentials
64-
- `APPLE_ID`, `APPLE_APP_SPECIFIC_PASSWORD`, `APPLE_TEAM_ID`: notarization credentials
47+
## Contributing
6548

66-
Tag pushes and manual runs with `publish=true` fail unless Developer ID signing and notarization succeed. A manual run with `publish=false` may use ad-hoc signing for validation, but it never creates a GitHub release or updates Homebrew. Prerelease tags create GitHub prereleases but do not replace the stable Homebrew cask.
49+
See [CONTRIBUTING.md](CONTRIBUTING.md) for source builds, tests, packaging, and release instructions.

0 commit comments

Comments
 (0)