Updating build/relese info

BUILDERS.README

@@ -0,0 +1,166 @@
+Notes for builders of biber binaries for distribution via CTAN and TeXLive
+==========================================================================
+
+INTRODUCTION
+------------
+
+Biber is a perl program which is "packed" into a stand-alone executable
+using the perl "pp" program which is part of the PAR::Packer module. The
+resulting binary is a completely self-contained perl installation including
+all modules and libraries needed. No perl installation is needed to run
+biber. On the first run, biber unpacks itself into a cache into a temporary
+platform-dependent location. This takes a little longer than a normal run
+as the one-time cache unpacking operation has some overhead. The location
+of the cache can be viewed by running, after the initial unpack run:
+
+biber --cache
+
+This cache can safely be deleted and biber will simply unpack itself again
+on the next run.
+
+For developers and the more adventurous, Biber can be run as a raw perl
+program from the github source and this requires perl to be installed.
+After fetching the github sources, run "perl Build.PL" and then "Build
+installdeps" to check the minimum perl requirements and install all
+required modules. You will also need to install the perl "PAR::Packer"
+module in order to build a binary version.
+
+BUILDING A biber EXECUTABLE
+---------------------------
+In the dist/ directory of the source tree, you will find subdirectories
+named after various platforms. The directories each contain a "build.sh"
+bash script which is used to build a biber binary using "pp". To build
+biber for a new platform, simply copy an existing script and adopt it to
+your platform. The script basically just calls "pp" with various arguments
+which are mostly there to force the inclusion of modules and libraries
+which are not automatically detected by Module::ScanDeps for various
+reasons (usually, because the modules/libs are implicitly rather than
+explicitly mentioned in the code).
+
+See the biber documentation in the doc/ directory for details on the build
+process.
+
+RELEASING BIBER on CTAN
+-----------------------
+
+*****
+PLEASE open a ticket in the biber githib repo:
+
+https://github.com/plk/biber/issues
+
+if you wish to provide a binary to CTAN/TexLive to make sure someone isn't
+already doing this
+*****
+
+
+
+
+The biber maintainers will make a new release from a new version tag when
+a new biber version is releases. Please subscribe to new releases of
+
+https://github.com/plk/biber
+
+to be notified when a new biber release is made so that you can build your
+binaries from the release tag. New releases are usually only made a few
+times per year.
+
+Builders can then upload their binaries directly to CTAN at:
+
+https://ctan.org/upload
+
+The name of the package should be:
+
+biber-<platform>
+
+The upload should consist of an archive containing only the following:
+
+* A README
+* A single binary called "biber" ("biber.exe" for Windows platforms)
+
+The archive should be named as follows:
+
+biber-<version>-<platform>.<extension>
+
+where:
+
+<version> is the biber version being built
+<platform> is the platform name and has no particular format requirements
+           as long as it is clear
+
+<extension> is the archive format extension and you are free to use any
+            commonly recognised format, e.g:
+
+.tar.gz
+.tgz
+.tar.xz
+.zip
+
+For example:
+
+biber-2.18-darwin_x86_64.tar.gz
+biber-2.18-linux_x86_64.tar.xz
+biber-2.18-MSWIN64.zip
+
+Note: If it necessary to push a fix for a particular platform in between
+biber releases, in a case for example where there is an issue with the
+build but there is no change in biber, you should append a dash "-"
+followed by a montonically increasing integer so that it is clear that the
+release is the same biber version but is a later version of the build for
+that platform, e.g:
+
+biber-2.18-1-darwin_x86_64.tar.gz
+biber-2.18-2-linux_x86_64.tar.gz
+biber-2.18-3-MSWIN64.zip
+
+** DO NOT change the name of the binary inside the archive - it should
+   always be "biber" or "biber.exe"
+
+This makes it clear that the biber version remains the same and all that is
+changed is some aspect of the binary cache infrastructure for the platform.
+
+The README should simple contain the following where <platform> is as
+described above:
+
+------
+These are biber binaries for the <platform> platform(s).
+See https://ctan.org/pkg/biber for documentation, sources, and all else.
+------
+
+When uploading to CTAN, use the biber version as the version number (with
+any platform-specific addition as mentioned above), e.g:
+
+2.18
+2.18-2
+
+The "Suggested CTAN directory" should be a subdir of biblio/biber, e.g:
+
+biblio/biber/biber-linux
+biblio/biber/biber-linux-musl
+biblio/biber/biber-macosx
+biblio/biber/biber-solaris-intel
+biblio/biber/biber-windows
+biblio/biber/biber-cygwin
+
+Again, the directory name is not particularly important, as long it
+describes the platform specifically enough. Please re-use the directory for
+all future releases to make things easier for the CTAN maintainers.
+
+Builders are free to upload binary releases in between biber releases to
+fix binary issues but should not release new biber version binaries until a
+new biber version release has been made on github. TO be notified of new
+releases, you can subscribe to release notifications on github for biber.
+
+
+BINARIES ALSO AVAILABLE ON SOURCEFORGE
+--------------------------------------
+Binaries can and usually are also uploaded to Sourceforge as people have
+historically obtained them from there manually when required:
+
+https://sourceforge.net/projects/biblatex-biber/files/biblatex-biber/
+
+Please open a ticket in the biber github repo if you require permissions to
+do this.
+
+The biber maintainers regularly upload a development binary version of biber to
+Sourceforge so that people can try out fixes ahead of releases.
+

MANIFEST

@@ -40,6 +40,7 @@ lib/Biber/UCollate.pm
 lib/Biber/Utils.pm
 MANIFEST
 README.md
+BUILDERS.README
 TODO.org
 t/annotations.t
 t/basic-misc.t

README.md

@@ -46,9 +46,10 @@ More information, bugfix releases, forums and bug tracker are available at:
 
 ## BUILDING
 
-If you wish to build you own binary, see the main biber PDF documentation.
-There is a section there on how to do this. The PDF documentation is in the
-`documentation` folder for the release on Sourceforge.
+If you wish to build you own binary, see the main biber PDF documentation
+and particularly the included BUILDERS.README file
+The PDF documentation is in the `documentation` folder for the release on
+Sourceforge.
 
 ## LICENCE
 

RELEASE

@@ -9,6 +9,8 @@
 * "perl Build.PL" and "Build dist" to update YAML/JSON
 * Run test suite and make sure it passes cleanly
 * Commit and tag with version number
+* Create new github release so that builders can subscribe to know when a
+  new release is made
 * Move "current" to version number on SF
 * Create "current" folder using SF GUI
 * Create a new empty version tree for new version, use the dist/empty_tree.sh script: