Skip to content

Latest commit

 

History

History
86 lines (64 loc) · 3.54 KB

CONTRIBUTING.md

File metadata and controls

86 lines (64 loc) · 3.54 KB

Contributing

Contributions are welcome!

  1. Make your own fork of this repo
  2. Make your changes in a branch, in your own repo.
  3. If you add any new files, please make sure the Apache license header is included up top.
  4. When you are done coding, be sure to run test.sh and make sure that it passes!
  5. When your code is ready and the tests are passing, open up a pull request against our master branch.

If you have bug reports or feature requests, please open a GitHub Issue, and we'll get to it ASAP.

Building

./gradlew build

Note that this runs the integration tests, which can be rather slow. To run only the regular unit tests:

./gradlew test

Releasing

We use the gradle-maven-publish-plugin to publish to Sonatype OSS (and from thence to Maven Central), and the `com.gradle.plugin-publish plugin to publish to the Gradle Plugin Portal. Each of these plugins requires a fair bit of configuration.

Publishing to Sonatype

Pushing artifacts to Sonatype requires membership in the KeepSafe Sonatype org, which is by employment only. Once you have a login, put it in your private global Gradle file (e.g. ~/.gradle/gradle.properties, along with a valid GPG signing configuration. Your properties file should look like so:

SONATYPE_NEXUS_USERNAME=<your username here>
SONATYPE_NEXUS_PASSWORD=<your password here>
signing.secretKeyRingFile=/path/to/your/.gnupg/secring.gpg
signing.keyId=<short hex key ID>
signing.password=<password associated with the key>

Publishing to the Gradle Plugin Portal

Publishing to the Gradle Plugin Portal also requires credentials tied to your employment. You'll need an API key and secret from https://plugins.gradle.org. Put them in your global Gradle properties file like so:

gradle.publish.key=<your API key>
gradle.publish.secret=<your secret here>

Note that the Plugin Portal is incredibly lame and does not have a notion of more than one person being able to publish artifacts. Consequently, we need to share credentials; in practice, only @benjamin-bader has the keys.

Release Script

  1. git checkout master
  2. Edit version number in gradle.properties, remove "-SNAPSHOT" suffix
  3. Edit version number in README.md
  4. Edit version number in docs/index.html
  5. Update CHANGELOG.md
  6. git add . && git commit -S -m "Release version <version number here>
  7. git tag -s -a <version number> -m "Release version <version number>"
  8. ./gradlew clean check
  9. ./gradlew uploadArchives
  10. ./gradlew publishPlugins
  11. Edit version number in gradle.properties to the next SNAPSHOT version.
  12. git add . && git commit -S -m "Prepare next development version"
  13. git push --tags
  14. Go to https://oss.sonatype.org, log in
  15. Click "Staging Repositories"
  16. Select the appropriate repo, then click "Close", then wait
  17. Once closed, select the repo and click "Release", then wait

Working with the website

We use mkdocs with the Material theme. Follow the instructions at each link to install all the things.

The site is generated from the Markdown files in docs/, according to the template and settings in mkdocs.yml. The general workflow is:

  1. mkdocs serve
  2. Open the browser to http://localhost:8000
  3. Edit docs and/or mkdocs.yml
  4. Look at the changes in the browser
  5. Repeat as necessary
  6. Open a doc PR
  7. Once merged, mkdocs gh-deploy