JAL-3675 JAL-3570 JAL-3608 JAL-2983 release notes and docs

[jalview.git] / doc / building.md

diff --git a/doc/building.md b/doc/building.md
index 398181a..ad19979 100644 (file)
--- a/doc/building.md
+++ b/doc/building.md
@@ -165,6 +165,7 @@ Within the `jalview` folder you will find (of possible interest):
  `utils/install4j/`  | files used by the packaging tool, install4j
  `build.gradle`      | the build file used by gradle
  `gradle.properties` | configurable properties for the build process
+ `RELEASE`          | propertyfile configuring JALVIEW_VERSION (from jalview.version) and the release branch (from jalview.release). An alternative file can be specified via JALVIEW_RELEASE_FILE property
 
 Note that you need a Java 11 JDK to compile Jalview whether your target build is Java 1.8 or Java 11.
 
@@ -422,7 +423,7 @@ There are several values of `CHANNEL` that can be chosen, with a default of `LOC
       Note that bamboo_planKey should be set by the build plan with `-Pbamboo_planKey=${bamboo.planKey}`
     - application subdir as `alt`
     - Getdown launcher cannot use a `file://` scheme appbase. 
-* `DEVELOP`: This is for creating a `develop` appbase channel on the main web server.  This won't become live until the actual getdown artefact is synced to the web server.
+* `DEVELOP`: This is for creating a `develop` appbase channel on the main web server. This won't become live until the actual getdown artefact is synced to the web server.
   It will set
     - `appbase` as `http://www.jalview.org/getdown/develop/JAVA_VERSION`
     - application subdir as `alt`
@@ -465,6 +466,13 @@ e.g.
 gradle getdown -PCHANNEL=SCRATCH-my_test_version
 ```
 
+#### JALVIEW_VERSION and the RELEASE file
+Any Jalview build will include the value of JALVIEW_VERSION in various places, including the 'About' and Jalview Desktop window title, and in filenames for the stand-alone executable jar. You can specify a custom version for a build via the JALVIEW_VERSION property, but for most situations, JALVIEW_VERSION will be automatically configured according to the value of the CHANNEL property, using the `jalview.version` property specified in the RELEASE file:
+  - `CHANNEL=RELEASE` will set version to jalview.version
+  - `CHANNEL=TEST or DEVELOP` will append '-test' or '-develop' to jalview.version
+  
+It is also possible to specify a custom location for the RELEASE file via an optional JALVIEW_RELEASE_FILE property.
+
 #### `install4jMediaTypes`
 If you are building *install4j* installers (requires *install4j* to be installed) then this property specifies a comma-separated 
 list of media types (i.e. platform specific installers) *install4j* should actually build.