Skip to content

Latest commit

 

History

History
152 lines (117 loc) · 5.67 KB

RELEASING.md

File metadata and controls

152 lines (117 loc) · 5.67 KB
Raw

Releasing

In general it is desirable to release all aspects of DevFun even for untouched modules for point-releases etc.
This is to done to simplify the documentation and installation process for users, as well as for our own sanity, rather than having different versions for every other module.

Release Process

Due to the different module types/aspects (a Gradle plugin, java and android libs, Dokka/Javadoc generation, GitHub pages, etc.) there are a number of steps that need to be run in a specific order:

  1. Finalize and tag release commit (latest git tag is in referenced in documentation)
  2. Update UML (if needed)
  3. Update Doctoc (README, RELEASING, and Wiki etc.) before GH Pages as it may affect Wiki object line numbers
  4. Update GitHub Pages must be done before artifact release for documentation linking
  5. Build/upload Artifacts
  6. Merge/push changes/tags etc. should be done after artifacts are deployed to ensure README is valid at time of push

PlantUML

PlantUML is used to generate UML images (gh-pages/assets/uml/).

To (re)generate UML images/image maps:

./gradlew renderPlantUml

To preview PlantUML in the IDE there is an IntelliJ/Android Studio plugin.
For linux (and probably Mac, not sure about Windows) you will also need graphviz:

sudo apt install graphviz

Doctoc

Doctoc is used to generate the README and various Wiki entries table of contents.

Install using npn:

npm install -g doctoc

It is used for the README and RELEASING documents and should be run whenever they are altered:

doctoc *.md --github --notitle

It is also used in the Wiki (currently only Components.kt), however the Dokka task will handle that automatically (see dokka/build.gradle.kts#L126), but if need be can be run manually (due to issues with Dokka generation we need to adjust the output with sed as well):

doctoc dokka/src/main/java/wiki/Components.kt --github --notitle && sed '/<!-- START doctoc generated TOC/,/<!-- END doctoc generated TOC/s/^( *)/ * \1\1/' -ri dokka/src/main/java/wiki/Components.kt

GitHub Pages

Both the external documentation and "wiki" use GitHub Pages.

Artifact Javadoc generation (via Dokka) links the external documentation during generation of artifacts, thus it is necessary to do this prior to that (specifically, Dokka looks for the generated package-list file).

  1. Checkout gh-pages branch in project directory named gh-pages (folder is in main project .gitignore)
    Alternatively checkout elsewhere and create symlink:

    git clone -b gh-pages --single-branch git@github.com:NextFaze/dev-fun.git gh-pages
ln -s path/to/gh-pages gh-pages # if cloned elsewhere

  2. Update GH-Pages (Dokka)
    Run dokka task (this will also clear previously generated Dokka files):

    ./gradlew dokka

  3. Commit/push changes: (substitute version)

    cd gh-pages
git add .
git commit -m "Update for 2.1.0"
git tag 2.1.0-pages
git push && git push --tags

Artifacts

All libraries/modules/plugins should be tagged/published as the latest version even if there were no changes to simplify the documentation and installation process for users.

When adding a new module you also need to tell BinTray to add the artifact to JCenter (via bintray on the artifact's page).
The final push/merge to master should be delayed until you receive the notification from JCenter that the artifact has been added (~12 hours).

Modules

  • Note: Due to Gradle and/or BinTray plugin issues, parallel task execution may result in skipped/empty uploads!
    Typically this is enabled with org.gradle.parallel=true in your user/project gradle.properties.
    You can tell if you have it enabled if the first line of your Gradle output has something like "Parallel execution is an incubating feature".
    • If this is enabled, you must disable it (and ./gradlew --stop), or manually call each module's :module:bintrayUpload task to ensure successful deployment.

This should be done after GitHub Pages (Dokka) due to external documentation linking.

  • Snapshots are defined by gradle.properties value VERSION_SNAPSHOT (true/false).
  • Remember to check BinTray task options dryRun, publish, and override, and also mavenCentralSync.sync.
./gradlew clean bintrayUpload

This can take 10-15 minutes!

Gradle Plugin

This should be done after the artifacts are updated.

./gradlew publishPlugins

TLDR;

  • On local copy merge in release to master, and if needed, run doctoc, uml generation, etc.
  • Turn off snapshot flag VERSION_SNAPSHOT=false in gradle.properties
  • Turn off dryRun flag DEVFUN_BINTRAY_DRY_RUN=false in gradle.properties
  • Ensure gradle parallel is turned off (org.gradle.parallel=false)
  • Run commands: 
    git tag 2.1.0
./gradlew clean
./gradlew assemble
./gradlew dokka
./gradlew bintrayUpload
./gradlew publishPlugins
cd gh-pages
git add .
git commit -m "Update for 2.1.0"
git tag 2.1.0-pages
git push && git push --tags
cd ..
git push && git push --tags