+1 Dave's proposal sounds good to me in principle. I have three questions, though:
- Will that mean that we will update the source tar files on the download page for a release, after it has been made available? - Can the web site be built from documents that come from multiple git branches? - Any other problems with updating a branch after it has been released? For example, the Jenkins test infrastructure is likely not there anymore, will it be easy to ensure that only documentation gets changed? About Steve's point: Yes, we (I) need to be better at updating the documentation in time, I know I definitely need to learn more about how to do that. But I like the idea that in exceptional cases we can correct mistakes in the documentation after a release is done. Maybe the document version should say that (e.g. SQL Reference Manual, version 2.0.0, last corrected on Aug 15., 2016). Thanks, Hans On Thu, May 26, 2016 at 8:53 AM, Steve Varnau <[email protected]> wrote: > +1 > > We should not be waiting until end of release to document new features. > That > is why we have the docs in same repo as the code. We contributors and > reviewers need to think about docs that need update along with code > changes. > > --Steve > > > > -----Original Message----- > > From: Dave Birdsall [mailto:[email protected]] > > Sent: Thursday, May 26, 2016 8:31 AM > > To: [email protected] > > Subject: How the manuals are built for back releases > > > > Hi, > > > > > > > > At the moment, our Trafodion manuals are lagging the code a little bit. > > (Thanks to Gunnar Tapper for his Herculean efforts to bring them up to > > date.) > > > > > > > > Even though the apache/master branch is now 2.1, we have been making > > documentation changes for 2.0 to the apache/master branch. > > > > > > > > This has the following effects: > > > > > > > > 1. To build the Release 2.0 manuals, one has to build them on the > > latest branch (apache/master), but manually change the environment > > variables TRAFODION_VER to 2.0.0 and TRAFODION_VER_MINOR to 0. > > > > 2. The mvn post-site build step requires Jar files for DCS and > REST. > > If one doesn’t already have them built in one’s committer instance, one > > has > > to do a “make” to do this. But since the branch is apache/master, it > > reflects the 2.1 content, not 2.0. That means the external documentation > > for DCS and REST that goes into the 2.0.0 manuals will actually be 2.1. > > > > > > > > This isn’t a problem at the moment because the externals have not > diverged > > much as far as I know. But it’s probably not something we want to rely on > > in the long term. > > > > > > > > I think we are OK for now; but I’d like to propose that at some point > soon > > we change our development practices so that there is a strict > > correspondence between branches for documentation and code. So, for > > example, after Release 2.1 is released, any changes to the Release 2.1 > > manuals would go on the apache/release2.1 branch rather than > > apache/master. > > This still allows for development of 2.1 manuals to continue after the > 2.1 > > code is released, but it does so with what I think is a cleaner build > > process. > > > > > > > > Comments? > > > > > > > > Dave >
