For v 2.0+ we need to create an actual distribution package

[martindholmes]

In addition to supplying a sample config file with full comments, we should actually have a script which builds a distribution for end-users. We can exclude lots of bits and pieces such as the ci and jenkins folders, the documentation config file, and so on, making for a less cluttered package. We should also have a decent version of the built documentation, which needs to function locally (so can't have a search), but could point to the online version which does.

[martindholmes]

Starting a plan for this. We need:

1. a buildRelease.xml ant file.
2. a diagnostics.xsl file which checks a bunch of things before a release can be made.

The ant file should run the diagnostics, and parse the results to discover whether it's possible to proceed.
If not, it reports the fixes needed. These may be things like not being on a release branch; not having a documentation whatsnew div with the version matching the EDITION file; and more, as we think of things.
If so, it will:

• build the documentation to create the single HTML version for distribution;
• create a folder called release-x.y.z;
• copy all content into it;
• create zip and tar.gz archives of that folder.

Questions remaining:

1. Do we include the test content so the user can run a local test, or is that confusing?
2. Do we provide a sample template for a config file?
3. Do we include the documentation build process as another potentially useful test?

[martindholmes]

A pressing question before we can proceed with this:

Do we pre-build the JavaScript as part of the package creation, meaning that we can dispense with the Closure compiler in the distribution package, or do we leave that part of the build to be done every time? If we precompile, we'll have to rewrite the main build file to use the precompiled code instead of compiling it; it could look to see if a precompiled package is in a specific location and if so, use it, otherwise try to compile.

My instinct is to leave the compilation process as-is, and run it every time a site is indexed; that will make it easier for people to customize the JS. But it will mean that the distribution package is a little heavier.

[martindholmes]

I've completed a first implementation of this, and I now need to test it on some real projects.

[martindholmes]

Tweaked and tested, so PR coming.

[joeytakeda]

Thanks for all this, @martindholmes !

Re the compilation of the JS: I think it would be great if we could move away from compiling every time if possible (especially if we move toward ES6 modules rather than concatenation of files), but I think that's a different issue. So I think for now it's fine to leave the compilation process as-is, especially given that people won't be using the JS without running the build process anyway.

[martindholmes]

Yes, I think this could be a 2.1 change: the build process only compiles the js if there are no compiled versions, or if the source js is newer than the compiled versions. However that means that if you use the release package, you can't customize the js because (presumably) we no longer ship the compiler. You'd have to clone the repo to do any customization.

[martindholmes]

Moving this along to the 2.1 milestone, for consideration of distributing pre-compiled versions of the JS in the distro package.