+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
