That would be best, IMHO, if it is doable. Hans
On Thu, May 26, 2016 at 4:36 PM, Gunnar Tapper <[email protected]> wrote: > Hi, > > Likely, I can auto generate the last update (well, built) info. Is that > good enough? > > Thanks, > > Gunnar > > On Thu, May 26, 2016 at 1:22 PM, Carol Pearson <[email protected] > > > wrote: > > > <scurries out from her hole playing with billions of rows in Trafodion> > > > > +1 > > > > Having well-maintained documentation is key for users to have happy > > experiences. > > > > And +1 to Hans's suggestion for putting a last updated date at the top of > > the document. There's already version information after the license > > agreement, but right now the 2.0 version I have open on my screen has "To > > be announced" in the date box because we don't know when 2.0 comes out. > I > > like a date at the top with "last updated." I supposed there's a low > > chance of collisions if two people update the documentation on the same > day > > but that's an easy problem to sort out. > > > > <scurries back in - I have data to push around and query and select and > > update stats and create indexes on....> > > > > --------------------------------------------------------------- > > Email: [email protected] > > Twitter: @CarolP222 > > --------------------------------------------------------------- > > > > On Thu, May 26, 2016 at 11:45 AM, Hans Zeller <[email protected]> > > wrote: > > > > > Thanks, that sounds very good! > > > > > > Hans > > > > > > On Thu, May 26, 2016 at 9:22 AM, Steve Varnau <[email protected]> > > > wrote: > > > > > > > Good questions. > > > > > > > > The release2.0 branch will stay around, since it is where we would > make > > > > changes if we need/want to do a patch release (e.g., 2.0.1, > 2.0.2,...). > > > > Likewise, jenkins will keep doing pull-request chacks on that branch > if > > > > there are incoming changes, at least for some reasonable time while > > that > > > > branch is active. The daily tests will likely be dropped after the > > main > > > > release, so we are not running them every day for no code changes. > > > > > > > > The source tar, however, is only updated when we do an official > > release. > > > > Though even a patch release needs to go through the formal release > > > process. > > > > The web site update does not wait on official release, as it is > updated > > > > asynchronously. > > > > > > > > The docs build process was designed to create manuals in a > > > release-specific > > > > folder, so it is quite possible to build 2.0, switch branches, build > > 2.1, > > > > etc. Then copy the results over to the -site repo where they are > > > published > > > > to the web. > > > > > > > > --Steve > > > > > > > > > > > > > -----Original Message----- > > > > > From: Hans Zeller [mailto:[email protected]] > > > > > Sent: Thursday, May 26, 2016 9:06 AM > > > > > To: dev <[email protected]> > > > > > Subject: Re: How the manuals are built for back releases > > > > > > > > > > +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 > > > > > > > > > > > > > > > > > > > -- > Thanks, > > Gunnar > *If you think you can you can, if you think you can't you're right.* >
