trafodion-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gunnar Tapper <tapper.gun...@gmail.com>
Subject Re: How the manuals are built for back releases
Date Thu, 26 May 2016 23:36:17 GMT
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 <carol.pearson234@gmail.com>
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:    carol.pearson234@gmail.com
> Twitter:  @CarolP222
> ---------------------------------------------------------------
>
> On Thu, May 26, 2016 at 11:45 AM, Hans Zeller <hans.zeller@esgyn.com>
> wrote:
>
> > Thanks, that sounds very good!
> >
> > Hans
> >
> > On Thu, May 26, 2016 at 9:22 AM, Steve Varnau <steve.varnau@esgyn.com>
> > 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:hans.zeller@esgyn.com]
> > > > Sent: Thursday, May 26, 2016 9:06 AM
> > > > To: dev <dev@trafodion.incubator.apache.org>
> > > > 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 <
> steve.varnau@esgyn.com>
> > > > 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:dave.birdsall@esgyn.com]
> > > > > > Sent: Thursday, May 26, 2016 8:31 AM
> > > > > > To: dev@trafodion.incubator.apache.org
> > > > > > 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.*

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message