<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 > > > > > > >
