Contributing
Goldberry is Apache 2.0 with no contributor agreement, and every change passes the same gates whether it comes from a maintainer or from a stranger.
A change is a pull request against master on GitHub. This chapter says what the repository expects of one. The five chapters after it say how to build, where things live, what the tests check, how a release goes out, and how a decision is written down.
The licence
The code is under the Apache License 2.0. There is no CLA to sign. A pull request is a contribution under that licence, and LICENSE and NOTICE ship inside every jar under META-INF.
Third-party software is disclosed in THIRD-PARTY-NOTICES.md and licenses/, and the two are held together by a task:
./gradlew checkLicenses
A dependency named in one and not the other fails the build. The reasoning is in ADR-0015.
What a change passes
./gradlew check is the gate. CI runs the same thing on Linux, macOS and Windows, and a pull request is green only when all three are.
| Gate | What it holds | Fixed by |
|---|---|---|
| Formatting | Every Java file matches palantir-java-format | ./gradlew spotlessApply |
| Error Prone and NullAway | src/main compiles with no finding, and every package is @NullMarked | Reading the finding |
| PMD | The hand-picked rules in config/pmd/ruleset.xml | Reading the finding |
| SpotBugs | Reports only. build/reports/spotbugs/main.html per module | Nothing yet |
| Tests, twice | The suite passes bound reflectively and again woven | The test, or the code |
| Goldens | Every reference image still matches what the code draws | ./gradlew blessGoldens, then review the diff |
| Export list | Every symbol bound in Java is exported, and nothing exported is unbound | Editing goldberry.symbols |
package-info | Every package has one, with a doc comment and @NullMarked | Writing it |
| Javadoc | A [link] in a published module resolves | Fixing the link |
| Markdown | No trailing whitespace, a final newline | ./gradlew formatMarkdown |
| Licences | THIRD-PARTY-NOTICES.md and licenses/ agree | Editing both |
Tests and gates says what each one runs and why. The record behind the format-and-analysis tier is ADR-0497, and the record behind the two test runs is ADR-0155.
Tip
Run
./gradlew spotlessApply checkbefore pushing. The formatter is the one gate that fixes itself.
A widget arrives whole
A new widget is not done when it draws. docs/testing.md §5 says what it arrives with, and the rule is before review, not after:
- a row in the widget specification, in the
core-widgets.mdformat; - a row of design-system metrics;
- a page in the showcase gallery;
- semantics assertions, so the sweep finds a role and a name;
- golden images, in both themes and at both densities.
The gallery is the demo, the visual-regression corpus and the accessibility sweep at once, so a widget that is not in it is not tested. Writing a widget walks through the code. The sweeps that read the registry are in Tests and gates.
Decisions are recorded
A change that chooses between designs gets an architecture decision record beside the code, in the same pull request. The log is the last part of this book, and ADR-0001 says why it exists. Recording a decision says how to write one and what the build checks about it.
The chapters
Where to ask
Open an issue at https://github.com/DigitalSmile/goldberry/issues. A bug report is most useful with the platform, the display scale, and the start-up timeline the toolkit logs at TRACE. Logging and diagnostics says how to turn that on.
Status says what is built, and TODO says what is deferred and why. A question that one of those answers is answered there first.