Skip to content

Developer Guide

Jump to bottom
Nepomuk Seiler edited this page Sep 9, 2018 · 17 revisions

This should provide some information on how to contribute, develop and do stuff around sbt-native-packager.

Testing

Most (all?) tests in sbt-native-packager use the scripted library. This will fork a new instance of sbt and load a project, running commands specified in the test file.

For most ubuntu systems, you can run a "as much as possible" run via:

$ sbt
>  scripted universal/* debian/* rpm/*

The "native" tests are split by operating system, and then descriptive-ish name for what the test does. Current categories of tests:

  • osx - Tests creating dmg files - scripted osx/*
  • windows - Requires WiX 3.6 installation, testing creating MSIs - scripted windows/
  • cygwin - Requires cygwin installed in the default location. Tests generated BASH files in cygwin (pathing fun)
  • debian - Requires dpkg, tests constructing debian files - scripted debian/*
  • rpm - Requires rpmbuild, tests constructing rpm files - scripted rpm/*
  • universal - Requires zip, tar and xz. Tests generating OS-generic files, although it will use some OS native commands as these generally cause less issues than Java counterparts - scripted universal/*

You can run a specific test via the command scripted <test-group>/<test-type>.

Documentation

The documentation can be found under src/sphinx.

Build the docs

First you have to install the sphinx and necessary dependencies

sudo apt-get install python-sphinx python-pip
pip install sphinx_rtd_theme

Now start up sbt with sbt and start the automatic compilation with

~sphinx:generateHtml

Open the index.html at target/sphinx/html.

Publish GitHub Page

sbt ghpagesPushSite

Releasing

How to release a version to Bintray and create a release tag.

Configuring your system

Open sbt

> bintrayWhoami
None
> bintrayChangeCredentials

Now you have configured bintray.

Next you need the github changelog generator tool available in your shell. You also need a github token and access to the sbt-native-packager.

Release and Publish

The recommended way is to release sbt-native-packager via travis. This requires two things

  1. Checkout the current master branch
  2. Create a tag with the version number you want to release, e.g.
git tag -as "v2.0.0"

A release tag must always start with v

Push and let travis do the work.

How does this work

  1. The travis.yml contains a release stage that is only executed when a tag starting with v is pushed.
  2. A encrypted tar file is decrypted which contasin
    1. A private pgp key for signing the jar
    2. A private ssh key which is added as a deploy key in sbt-native-packager to allow git push
  3. The travis.yml contains encrypted environment variables
    1. BINTRAY_USER and BINTRAY_PASS for bintray access
    2. CHANGELOG_GITHUB_TOKEN for github access to create the CHANGELOG.md
  4. The git repository clone is unshallowed and the remote is changed to ssh to be able to use the deploy key
  5. All required dependencies for the release process are installed. This includes
    1. github changelog generator
    2. sphinx and the sphinx_rtd_theme which is required to publish the github pages
  6. sbt-dynver takes care of the correct versioning.

Note that only the unit tests are executed. This assumes that only pull requests that have passed all tests are merged into master.

Details explained

Why not use the pgp key to encrypt files and instead use a tar file?

Future maintainers may want to keep the pgp key, but encrypt additional files. As I (@muuki88) have deleted the private pgp key, the only option to encrypt more files with pgp is to change the pgp key. IMHO the pgp key signing the package should not change constantly.

Why not use other sbt-plugins like release-early?

We already had some custom sbt-release steps in place. Besides, sbt-release wasn't the issue, but the travis setup ;)

Why not set the environment variables in the travis interface

They are pretty well hidden there. The travis.yml should be as self contained as possible.

Why add another release script and not a sbt-release step?

The prechecks would fail without a proper git setup

Resources

Create Release Notes

Use https://github.com/skywinder/github-changelog-generator . This is part of the automated release process.

Clone this wiki locally