Skip to content

Commit f04f2a8

Browse files
reidspencerclaude
reidspencer
and
claude
committed
Switch publishing from Sonatype to GitHub Packages
- Add symlink to GithubPublishing.scala in project/ - Update build.sbt to use GithubPublishing instead of SonatypePublishing - Add NOTEBOOK.md with engineering notes Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 6c16a97 commit f04f2a8

3 files changed

Lines changed: 170 additions & 2 deletions

File tree

‎NOTEBOOK.md‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
# Engineering Notebook: sbt-ossuminc
2+
3+
## Current Status
4+
5+
Version 1.1.0 has been tagged and pushed but not yet published. The build is currently configured for Sonatype publishing, but we need to switch to GitHub Packages.
6+
7+
## Work Completed (Recent)
8+
9+
- [x] Fixed ScalaJS helper to handle missing git commit/scmInfo gracefully
10+
- [x] Added deprecated `With.Javascript` alias for backward compatibility
11+
- [x] Updated all scripted tests to pass (14/14)
12+
- [x] Updated README.md with correct API documentation
13+
- [x] Committed and tagged v1.1.0
14+
- [x] Pushed to origin/main
15+
16+
## In Progress
17+
18+
- [ ] Switch publishing from Sonatype to GitHub Packages
19+
20+
## Plan: Switch to GitHub Packages Publishing
21+
22+
### Background
23+
24+
The `project/` directory uses symlinks to reference helper files from `src/main/scala/com/ossuminc/sbt/helpers/`. This allows the plugin to use its own functionality during its own build (bootstrapping).
25+
26+
Current symlinks in `project/`:
27+
- `AutoPluginHelper.scala` → `../src/main/scala/com/ossuminc/sbt/helpers/AutoPluginHelper.scala`
28+
- `DynamicVersioning.scala` → `../src/main/scala/com/ossuminc/sbt/helpers/DynamicVersioning.scala`
29+
- `Miscellaneous.scala` → `../src/main/scala/com/ossuminc/sbt/helpers/Miscellaneous.scala`
30+
- `Release.scala` → `../src/main/scala/com/ossuminc/sbt/helpers/Release.scala`
31+
- `RootProjectInfo.scala` → `../src/main/scala/com/ossuminc/sbt/helpers/RootProjectInfo.scala`
32+
- `Scala2.scala` → `../src/main/scala/com/ossuminc/sbt/helpers/Scala2.scala`
33+
- `SonatypePublishing.scala` (local file, not symlink)
34+
35+
### Steps to Switch to GitHub Packages
36+
37+
#### Step 1: Create symlink for GithubPublishing
38+
39+
```bash
40+
cd /Users/reid/Code/ossuminc/sbt-ossuminc/project
41+
ln -s ../src/main/scala/com/ossuminc/sbt/helpers/GithubPublishing.scala GithubPublishing.scala
42+
```
43+
44+
#### Step 2: Update build.sbt
45+
46+
Change the import from:
47+
```scala
48+
import com.ossuminc.sbt.helpers.{DynamicVersioning, RootProjectInfo, Scala2, SonatypePublishing}
49+
```
50+
51+
To:
52+
```scala
53+
import com.ossuminc.sbt.helpers.{DynamicVersioning, RootProjectInfo, Scala2, GithubPublishing}
54+
```
55+
56+
Change the configure call from:
57+
```scala
58+
.configure(SonatypePublishing.configure)
59+
```
60+
61+
To:
62+
```scala
63+
.configure(GithubPublishing.configure)
64+
```
65+
66+
#### Step 3: Set up GitHub Token
67+
68+
The `GithubPublishing` helper uses `sbt-github-packages` which looks for tokens in this order:
69+
1. Git config: `git config github.token`
70+
2. Environment variable: `GITHUB_TOKEN`
71+
72+
**Token Requirements:**
73+
- Must have `write:packages` scope for publishing
74+
- Must have `read:packages` scope for reading (if using private packages)
75+
- For organization repos, the token owner must have appropriate org permissions
76+
77+
**To set up the token:**
78+
79+
Option A - Environment variable (recommended for CI and one-time use):
80+
```bash
81+
export GITHUB_TOKEN=ghp_your_token_here
82+
```
83+
84+
Option B - Git config (persistent local setup):
85+
```bash
86+
git config --global github.token ghp_your_token_here
87+
```
88+
89+
#### Step 4: Publish
90+
91+
After setting `GITHUB_TOKEN`:
92+
```bash
93+
sbt publish
94+
```
95+
96+
### How GithubPublishing Works
97+
98+
The `GithubPublishing` helper (`src/main/scala/com/ossuminc/sbt/helpers/GithubPublishing.scala`):
99+
100+
```scala
101+
object GithubPublishing extends AutoPluginHelper {
102+
def configure(project: Project): Project = {
103+
project
104+
.enablePlugins(sbtghpackages.GitHubPackagesPlugin)
105+
.settings(
106+
githubOwner := RootProjectInfo.Keys.gitHubOrganization.value, // "ossuminc"
107+
githubRepository := RootProjectInfo.Keys.gitHubRepository.value, // "sbt-ossuminc"
108+
githubTokenSource := TokenSource.Or(
109+
TokenSource.GitConfig("github.token"),
110+
TokenSource.Environment("GITHUB_TOKEN")
111+
),
112+
publishMavenStyle := true,
113+
resolvers += Resolver.githubPackages(RootProjectInfo.Keys.gitHubOrganization.value),
114+
publishTo := githubPublishTo.value
115+
)
116+
}
117+
}
118+
```
119+
120+
The `RootProjectInfo.initialize("sbt-ossuminc", startYr = 2015)` call in `build.sbt` sets:
121+
- `gitHubOrganization` = "ossuminc" (default)
122+
- `gitHubRepository` = "sbt-ossuminc"
123+
124+
### Verification Checklist
125+
126+
Before publishing:
127+
- [ ] `GITHUB_TOKEN` environment variable is set
128+
- [ ] Token has `write:packages` scope
129+
- [ ] Symlink created: `project/GithubPublishing.scala`
130+
- [ ] `build.sbt` updated to use `GithubPublishing`
131+
- [ ] Run `sbt compile` to verify build still works
132+
- [ ] Run `sbt publish` to publish
133+
134+
### After Publishing
135+
136+
Update users to reference the new location in their `~/.sbt/1.0/github.sbt`:
137+
```scala
138+
credentials += Credentials(
139+
"GitHub Package Registry",
140+
"maven.pkg.github.com",
141+
"your-github-username",
142+
"your-github-token-with-read:packages-scope"
143+
)
144+
```
145+
146+
## Design Decisions Log
147+
148+
| Decision | Rationale | Alternatives Considered | Date |
149+
|----------|-----------|------------------------|------|
150+
| Switch from Sonatype to GitHub Packages | Sonatype publishing is deprecated for this project; GitHub Packages provides simpler auth for ossuminc org | Continue with Sonatype, use both | 2026-01-15 |
151+
| Use symlink approach | Consistent with existing pattern in project/ directory | Copy file, inline the settings | 2026-01-15 |
152+
| Renamed With.Javascript to With.ScalaJS | Clearer naming, matches the actual technology | Keep old name, add both | 2026-01-15 |
153+
154+
## Next Steps
155+
156+
1. **In new session with GITHUB_TOKEN set:**
157+
- Create the GithubPublishing symlink
158+
- Update build.sbt
159+
- Test with `sbt compile`
160+
- Publish with `sbt publish`
161+
162+
2. Commit the build.sbt changes (minor change, could be v1.1.1 or just a fix commit)
163+
164+
## Open Questions
165+
166+
- Should we remove the `project/SonatypePublishing.scala` file after switching?
167+
- Do we need to update CI/CD workflows for GitHub Actions?

‎build.sbt‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import com.ossuminc.sbt.helpers.{DynamicVersioning, RootProjectInfo, Scala2, SonatypePublishing}
1+
import com.ossuminc.sbt.helpers.{DynamicVersioning, GithubPublishing, RootProjectInfo, Scala2}
22

33
/*
44
* Copyright 2015-2025, Ossum Inc. All Rights Reserved.
@@ -23,7 +23,7 @@ lazy val `sbt-ossuminc` = project
2323
.configure(RootProjectInfo.initialize("sbt-ossuminc", startYr = 2015))
2424
.configure(DynamicVersioning.configure)
2525
.configure(Scala2.configure)
26-
.configure(SonatypePublishing.configure)
26+
.configure(GithubPublishing.configure)
2727
.settings(
2828
licenses += "Apache V2.0" -> url("https://www.apache.org/licenses/LICENSE-2.0"),
2929
name := "sbt-ossuminc",

‎project/GithubPublishing.scala‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../src/main/scala/com/ossuminc/sbt/helpers/GithubPublishing.scala

0 commit comments

Comments
 (0)