Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
55 lines (32 loc) · 3.98 KB

CONTRIBUTING.md

File metadata and controls

55 lines (32 loc) · 3.98 KB
Raw

Contributing to anyColorPicker

Contributions of all types are welcome. We use GitHub to host code, track issues, enhancements, and perform project management.

anyColorPicker is released under the Apache 2.0 license.

This document should help you get started.

Filing issues

In order to create a new feature request or bug report just file an issue. To file a new issue, please use our issue template and fill out the template as much as possible (remove irrelevant parts). The more information you can provide, the more likely we are to be able to help. Please help us to speed up problem diagnosis by providing as much information as possible. Ideally, that would include a small sample project, gist or code snippet that reproduces the problem.

Contributing

master is the single permanent branch:

  • Create feature branches off master.
  • Send pull requests targeting master (fork the repository if you don't have write access).
  • CI (build.yml) must pass before a pull request can be merged.

Versioning follows Semantic Versioning: public API is added only in a minor release and removed or changed incompatibly only in a major one, and a patch leaves it alone. CI runs scripts/check-api-removals.sh, which fails when a declaration in the API dumps at the last release tag is missing from its module's api/; run it before proposing an API change. It catches removed declarations and changed signatures, not a class losing a supertype, so that still needs a reviewer's eye.

API conventions

Decisions that shape the public API, so the next one is made the same way. Add to this list when a new one is settled.

  • A set of options is an enum, even one that may grow, as every one in the library is: ColoringMode, PlaneRendering, EdgeSolver, Exactness, AnalogousCategory, HexAlpha and CssSyntax. An app can keep an enum in saved UI state: rememberSaveable { mutableStateOf(mode) } saves one on Android and cannot save a class, which would crash the app on rotation. An option added to an enum breaks callers' exhaustive when, so it waits for a major release.
  • Sliders, planes and pickers take enabled after modifier and before onValueChangeFinished: () -> Unit = {}, and a component's main content slot comes last.
  • Default slot content lives in ColorPickerDefaults, as SliderThumb, SliderLabel and Plane do.
  • A public constant is a val, not a const val, which would be copied into every caller's compiled code.
  • A constructor a factory already covers requires ExperimentalColorSpaceApi, so it can gain parameters in a minor release.

Code style

Our code style is defined via the .editorconfig file at the repository root; most IDEs (including IntelliJ IDEA and Android Studio) pick it up automatically.

When submitting code, please make every effort to follow existing conventions and code style in order to keep the code as readable as possible.

Testing

Tests in commonTest are the primary suite. They run as JVM tests and as Android host (unit) tests, so no device, emulator, or simulator is required to validate most changes.

Building

CI installs Zulu 21 to bootstrap Gradle; the daemon itself auto-provisions JetBrains Runtime 21 per gradle/gradle-daemon-jvm.properties (criteria: JETBRAINS 21). To change it run:

./gradlew updateDaemonJvm --toolchain-version=N --toolchain-vendor=VENDOR

Note that gradle/gradle-daemon-jvm.properties is generated by the updateDaemonJvm task — do not edit it by hand.

Release process

Releases are tag-driven. Bump VERSION_NAME in gradle.properties, add the version's section to CHANGELOG.md, and merge. Pushing the tag vX.Y.Z on the merge commit runs publish.yml, which refuses a tag that disagrees with VERSION_NAME, runs the tests, apiCheck and scripts/check-api-removals.sh, publishes to Maven Central and creates the GitHub Release. Running the workflow by hand publishes VERSION_NAME-SNAPSHOT unless snapshot is unticked.