You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@trafodion.apache.org by Gunnar Tapper <ta...@gmail.com> on 2016/07/06 22:08:51 UTC
[DISCUSS] Documentation Versioning
Hi,
I noticed that Steve 2.0.x header for the documentation. I think this is
preferable.
However, I know that we want to move to a model where the documentation
update is part of the release rather than done against the master post
release.
The current scheme is that we place documentation in a latest directory as
well as a versioned directory. This means that you have to; for example,
build 2.0.x documents setting $TRAFODION_VER to "2.0.0" to ensure that the
documents are placed on the correct versioned directory. The result will be
that the version-dependent documents are placed in
http://trafodion.apache.org/docs/2.0.0/*.
Moving forward, I think it'd be better if we create a $DOCS_VER or
something like that to allow for dot releases without having to create dot
releases of the documentation.
Thoughts?
--
Thanks,
Gunnar
*If you think you can you can, if you think you can't you're right.*
Re: [DISCUSS] Documentation Versioning
Posted by Gunnar Tapper <ta...@gmail.com>.
This also says that we need to separate documentation updates from website
updates since the latter is on the main branch by definition.
On Thu, Jul 7, 2016 at 1:17 PM, Steve Varnau <st...@esgyn.com> wrote:
> Yes, the pre-release docs are visible in the "Latest (in development)"
> section.
>
> I checked with Dave, and he said he put a note in his documentation change
> to indicate that it does not apply to 2.0, it is a work-around, but for now
> it is okay to use master version for 2.0.
>
> From here on, though, I think we need to assume master branch docs are for
> 2.1 only. Any more 2.0.x changes need to be backported.
>
> --Steve
>
>
> > -----Original Message-----
> > From: Gunnar Tapper [mailto:tapper.gunnar@gmail.com]
> > Sent: Thursday, July 7, 2016 12:06 PM
> > To: dev@trafodion.incubator.apache.org
> > Subject: Re: [DISCUSS] Documentation Versioning
> >
> > Hi Steve,
> >
> > Then, should the pre-release documentation (in this case, 2.1) be added
> to
> > the website so that it's visible? Or, do should developers to build the
> > website and the documentation as part of doing testing so that it can be
> > reviewed and updated?
> >
> > It seems to me that the latter is the better approach. If so, then I'll
> > update the Contributor Guide to include instructions on how to run the
> > website locally.
> >
> > Or, are there other suggestions?
> >
> > Thanks,
> >
> > Gunnar
> >
> > On Thu, Jul 7, 2016 at 12:27 PM, Steve Varnau <st...@esgyn.com>
> > wrote:
> >
> > > Gunnar,
> > >
> > > As we discussed earlier, once the code branches (master vs.
> release2.0),
> > > then the docs should be generated relative to the branch. So the MINOR
> > > version is still 0 on the release2.0 branch.
> > >
> > > I'm not certain we can say the master branch docs are still for 2.0,
> > > since
> > > there may have been doc changes for features that are for 2.1.
> > >
> > > For instance, it looks like this change included code and doc changes,
> > > which
> > > is what we want developers to do! But it means the master branch docs
> > > are
> > > no longer matching the 2.0 release.
> > >
> > > [TRAFODION-2044] Support SALT clause on CREATE TABLE LIKE
> > > M docs/messages_guide/src/asciidoc/_chapters/parser_msgs.adoc
> > > M docs/messages_guide/src/asciidoc/_chapters/sqlstate.adoc
> > > M docs/sql_reference/src/asciidoc/_chapters/sql_statements.adoc
> > >
> > > --Steve
> > >
> > >
> > > > -----Original Message-----
> > > > From: Gunnar Tapper [mailto:tapper.gunnar@gmail.com]
> > > > Sent: Wednesday, July 6, 2016 11:17 PM
> > > > To: dev@trafodion.incubator.apache.org
> > > > Subject: Re: [DISCUSS] Documentation Versioning
> > > >
> > > > Hi Steve,
> > > >
> > > > From what I see, these variables are defined in core/sqf/sqenvcom.sh.
> > > > However, TRAFODION_VER_MINOR is set to 1 in the main branch already.
> > That
> > > > works once the documentation updates are done as part of the release
> > > > rather
> > > > than post release as today.
> > > >
> > > > For now, what can be done to override these variables for the
> > > > documentation
> > > > part of the build?
> > > >
> > > > Gunnar
> > > >
> > > > On Wed, Jul 6, 2016 at 4:29 PM, Steve Varnau <steve.varnau@esgyn.com
> >
> > > > wrote:
> > > >
> > > > > Gunnar,
> > > > >
> > > > > Yes, that makes sense to me.
> > > > >
> > > > > Either that, or the docs could use only the major/minor numbers of
> > > > > the
> > > > > release -- at least for the directory path where to generate the
> > > > > docs.
> > > > > We
> > > > > probably want the update number in the docs, but only want one
> > > > > version
> > > > > per
> > > > > minor release.
> > > > >
> > > > > docs/${TRAFODION_VER_MAJOR}.${TRAFODION_VER_MINOR}
> > > > >
> > > > > --Steve
> > > > >
> > > > >
> > > > > > -----Original Message-----
> > > > > > From: Gunnar Tapper [mailto:tapper.gunnar@gmail.com]
> > > > > > Sent: Wednesday, July 6, 2016 3:09 PM
> > > > > > To: dev@trafodion.incubator.apache.org
> > > > > > Subject: [DISCUSS] Documentation Versioning
> > > > > >
> > > > > > Hi,
> > > > > >
> > > > > > I noticed that Steve 2.0.x header for the documentation. I think
> > > > > > this
> > > > > > is
> > > > > > preferable.
> > > > > >
> > > > > > However, I know that we want to move to a model where the
> > > > documentation
> > > > > > update is part of the release rather than done against the master
> > > post
> > > > > > release.
> > > > > >
> > > > > > The current scheme is that we place documentation in a latest
> > > > > > directory
> > > > > as
> > > > > > well as a versioned directory. This means that you have to; for
> > > > > > example,
> > > > > > build 2.0.x documents setting $TRAFODION_VER to "2.0.0" to ensure
> > > that
> > > > > the
> > > > > > documents are placed on the correct versioned directory. The
> > > > > > result
> > > > > > will
> > > > > > be
> > > > > > that the version-dependent documents are placed in
> > > > > > http://trafodion.apache.org/docs/2.0.0/*.
> > > > > >
> > > > > > Moving forward, I think it'd be better if we create a $DOCS_VER
> or
> > > > > > something like that to allow for dot releases without having to
> > > create
> > > > > dot
> > > > > > releases of the documentation.
> > > > > >
> > > > > > Thoughts?
> > > > > >
> > > > > > --
> > > > > > Thanks,
> > > > > >
> > > > > > Gunnar
> > > > > > *If you think you can you can, if you think you can't you're
> > > > > > right.*
> > > > >
> > > >
> > > >
> > > >
> > > > --
> > > > Thanks,
> > > >
> > > > Gunnar
> > > > *If you think you can you can, if you think you can't you're right.*
> > >
> >
> >
> >
> > --
> > Thanks,
> >
> > Gunnar
> > *If you think you can you can, if you think you can't you're right.*
>
--
Thanks,
Gunnar
*If you think you can you can, if you think you can't you're right.*
RE: [DISCUSS] Documentation Versioning
Posted by Steve Varnau <st...@esgyn.com>.
Yes, the pre-release docs are visible in the "Latest (in development)"
section.
I checked with Dave, and he said he put a note in his documentation change
to indicate that it does not apply to 2.0, it is a work-around, but for now
it is okay to use master version for 2.0.
From here on, though, I think we need to assume master branch docs are for
2.1 only. Any more 2.0.x changes need to be backported.
--Steve
> -----Original Message-----
> From: Gunnar Tapper [mailto:tapper.gunnar@gmail.com]
> Sent: Thursday, July 7, 2016 12:06 PM
> To: dev@trafodion.incubator.apache.org
> Subject: Re: [DISCUSS] Documentation Versioning
>
> Hi Steve,
>
> Then, should the pre-release documentation (in this case, 2.1) be added to
> the website so that it's visible? Or, do should developers to build the
> website and the documentation as part of doing testing so that it can be
> reviewed and updated?
>
> It seems to me that the latter is the better approach. If so, then I'll
> update the Contributor Guide to include instructions on how to run the
> website locally.
>
> Or, are there other suggestions?
>
> Thanks,
>
> Gunnar
>
> On Thu, Jul 7, 2016 at 12:27 PM, Steve Varnau <st...@esgyn.com>
> wrote:
>
> > Gunnar,
> >
> > As we discussed earlier, once the code branches (master vs. release2.0),
> > then the docs should be generated relative to the branch. So the MINOR
> > version is still 0 on the release2.0 branch.
> >
> > I'm not certain we can say the master branch docs are still for 2.0,
> > since
> > there may have been doc changes for features that are for 2.1.
> >
> > For instance, it looks like this change included code and doc changes,
> > which
> > is what we want developers to do! But it means the master branch docs
> > are
> > no longer matching the 2.0 release.
> >
> > [TRAFODION-2044] Support SALT clause on CREATE TABLE LIKE
> > M docs/messages_guide/src/asciidoc/_chapters/parser_msgs.adoc
> > M docs/messages_guide/src/asciidoc/_chapters/sqlstate.adoc
> > M docs/sql_reference/src/asciidoc/_chapters/sql_statements.adoc
> >
> > --Steve
> >
> >
> > > -----Original Message-----
> > > From: Gunnar Tapper [mailto:tapper.gunnar@gmail.com]
> > > Sent: Wednesday, July 6, 2016 11:17 PM
> > > To: dev@trafodion.incubator.apache.org
> > > Subject: Re: [DISCUSS] Documentation Versioning
> > >
> > > Hi Steve,
> > >
> > > From what I see, these variables are defined in core/sqf/sqenvcom.sh.
> > > However, TRAFODION_VER_MINOR is set to 1 in the main branch already.
> That
> > > works once the documentation updates are done as part of the release
> > > rather
> > > than post release as today.
> > >
> > > For now, what can be done to override these variables for the
> > > documentation
> > > part of the build?
> > >
> > > Gunnar
> > >
> > > On Wed, Jul 6, 2016 at 4:29 PM, Steve Varnau <st...@esgyn.com>
> > > wrote:
> > >
> > > > Gunnar,
> > > >
> > > > Yes, that makes sense to me.
> > > >
> > > > Either that, or the docs could use only the major/minor numbers of
> > > > the
> > > > release -- at least for the directory path where to generate the
> > > > docs.
> > > > We
> > > > probably want the update number in the docs, but only want one
> > > > version
> > > > per
> > > > minor release.
> > > >
> > > > docs/${TRAFODION_VER_MAJOR}.${TRAFODION_VER_MINOR}
> > > >
> > > > --Steve
> > > >
> > > >
> > > > > -----Original Message-----
> > > > > From: Gunnar Tapper [mailto:tapper.gunnar@gmail.com]
> > > > > Sent: Wednesday, July 6, 2016 3:09 PM
> > > > > To: dev@trafodion.incubator.apache.org
> > > > > Subject: [DISCUSS] Documentation Versioning
> > > > >
> > > > > Hi,
> > > > >
> > > > > I noticed that Steve 2.0.x header for the documentation. I think
> > > > > this
> > > > > is
> > > > > preferable.
> > > > >
> > > > > However, I know that we want to move to a model where the
> > > documentation
> > > > > update is part of the release rather than done against the master
> > post
> > > > > release.
> > > > >
> > > > > The current scheme is that we place documentation in a latest
> > > > > directory
> > > > as
> > > > > well as a versioned directory. This means that you have to; for
> > > > > example,
> > > > > build 2.0.x documents setting $TRAFODION_VER to "2.0.0" to ensure
> > that
> > > > the
> > > > > documents are placed on the correct versioned directory. The
> > > > > result
> > > > > will
> > > > > be
> > > > > that the version-dependent documents are placed in
> > > > > http://trafodion.apache.org/docs/2.0.0/*.
> > > > >
> > > > > Moving forward, I think it'd be better if we create a $DOCS_VER or
> > > > > something like that to allow for dot releases without having to
> > create
> > > > dot
> > > > > releases of the documentation.
> > > > >
> > > > > Thoughts?
> > > > >
> > > > > --
> > > > > Thanks,
> > > > >
> > > > > Gunnar
> > > > > *If you think you can you can, if you think you can't you're
> > > > > right.*
> > > >
> > >
> > >
> > >
> > > --
> > > Thanks,
> > >
> > > Gunnar
> > > *If you think you can you can, if you think you can't you're right.*
> >
>
>
>
> --
> Thanks,
>
> Gunnar
> *If you think you can you can, if you think you can't you're right.*
Re: [DISCUSS] Documentation Versioning
Posted by Gunnar Tapper <ta...@gmail.com>.
Hi Steve,
Then, should the pre-release documentation (in this case, 2.1) be added to
the website so that it's visible? Or, do should developers to build the
website and the documentation as part of doing testing so that it can be
reviewed and updated?
It seems to me that the latter is the better approach. If so, then I'll
update the Contributor Guide to include instructions on how to run the
website locally.
Or, are there other suggestions?
Thanks,
Gunnar
On Thu, Jul 7, 2016 at 12:27 PM, Steve Varnau <st...@esgyn.com>
wrote:
> Gunnar,
>
> As we discussed earlier, once the code branches (master vs. release2.0),
> then the docs should be generated relative to the branch. So the MINOR
> version is still 0 on the release2.0 branch.
>
> I'm not certain we can say the master branch docs are still for 2.0, since
> there may have been doc changes for features that are for 2.1.
>
> For instance, it looks like this change included code and doc changes,
> which
> is what we want developers to do! But it means the master branch docs are
> no longer matching the 2.0 release.
>
> [TRAFODION-2044] Support SALT clause on CREATE TABLE LIKE
> M docs/messages_guide/src/asciidoc/_chapters/parser_msgs.adoc
> M docs/messages_guide/src/asciidoc/_chapters/sqlstate.adoc
> M docs/sql_reference/src/asciidoc/_chapters/sql_statements.adoc
>
> --Steve
>
>
> > -----Original Message-----
> > From: Gunnar Tapper [mailto:tapper.gunnar@gmail.com]
> > Sent: Wednesday, July 6, 2016 11:17 PM
> > To: dev@trafodion.incubator.apache.org
> > Subject: Re: [DISCUSS] Documentation Versioning
> >
> > Hi Steve,
> >
> > From what I see, these variables are defined in core/sqf/sqenvcom.sh.
> > However, TRAFODION_VER_MINOR is set to 1 in the main branch already. That
> > works once the documentation updates are done as part of the release
> > rather
> > than post release as today.
> >
> > For now, what can be done to override these variables for the
> > documentation
> > part of the build?
> >
> > Gunnar
> >
> > On Wed, Jul 6, 2016 at 4:29 PM, Steve Varnau <st...@esgyn.com>
> > wrote:
> >
> > > Gunnar,
> > >
> > > Yes, that makes sense to me.
> > >
> > > Either that, or the docs could use only the major/minor numbers of the
> > > release -- at least for the directory path where to generate the docs.
> > > We
> > > probably want the update number in the docs, but only want one version
> > > per
> > > minor release.
> > >
> > > docs/${TRAFODION_VER_MAJOR}.${TRAFODION_VER_MINOR}
> > >
> > > --Steve
> > >
> > >
> > > > -----Original Message-----
> > > > From: Gunnar Tapper [mailto:tapper.gunnar@gmail.com]
> > > > Sent: Wednesday, July 6, 2016 3:09 PM
> > > > To: dev@trafodion.incubator.apache.org
> > > > Subject: [DISCUSS] Documentation Versioning
> > > >
> > > > Hi,
> > > >
> > > > I noticed that Steve 2.0.x header for the documentation. I think this
> > > > is
> > > > preferable.
> > > >
> > > > However, I know that we want to move to a model where the
> > documentation
> > > > update is part of the release rather than done against the master
> post
> > > > release.
> > > >
> > > > The current scheme is that we place documentation in a latest
> > > > directory
> > > as
> > > > well as a versioned directory. This means that you have to; for
> > > > example,
> > > > build 2.0.x documents setting $TRAFODION_VER to "2.0.0" to ensure
> that
> > > the
> > > > documents are placed on the correct versioned directory. The result
> > > > will
> > > > be
> > > > that the version-dependent documents are placed in
> > > > http://trafodion.apache.org/docs/2.0.0/*.
> > > >
> > > > Moving forward, I think it'd be better if we create a $DOCS_VER or
> > > > something like that to allow for dot releases without having to
> create
> > > dot
> > > > releases of the documentation.
> > > >
> > > > Thoughts?
> > > >
> > > > --
> > > > Thanks,
> > > >
> > > > Gunnar
> > > > *If you think you can you can, if you think you can't you're right.*
> > >
> >
> >
> >
> > --
> > Thanks,
> >
> > Gunnar
> > *If you think you can you can, if you think you can't you're right.*
>
--
Thanks,
Gunnar
*If you think you can you can, if you think you can't you're right.*
RE: [DISCUSS] Documentation Versioning
Posted by Steve Varnau <st...@esgyn.com>.
Gunnar,
As we discussed earlier, once the code branches (master vs. release2.0),
then the docs should be generated relative to the branch. So the MINOR
version is still 0 on the release2.0 branch.
I'm not certain we can say the master branch docs are still for 2.0, since
there may have been doc changes for features that are for 2.1.
For instance, it looks like this change included code and doc changes, which
is what we want developers to do! But it means the master branch docs are
no longer matching the 2.0 release.
[TRAFODION-2044] Support SALT clause on CREATE TABLE LIKE
M docs/messages_guide/src/asciidoc/_chapters/parser_msgs.adoc
M docs/messages_guide/src/asciidoc/_chapters/sqlstate.adoc
M docs/sql_reference/src/asciidoc/_chapters/sql_statements.adoc
--Steve
> -----Original Message-----
> From: Gunnar Tapper [mailto:tapper.gunnar@gmail.com]
> Sent: Wednesday, July 6, 2016 11:17 PM
> To: dev@trafodion.incubator.apache.org
> Subject: Re: [DISCUSS] Documentation Versioning
>
> Hi Steve,
>
> From what I see, these variables are defined in core/sqf/sqenvcom.sh.
> However, TRAFODION_VER_MINOR is set to 1 in the main branch already. That
> works once the documentation updates are done as part of the release
> rather
> than post release as today.
>
> For now, what can be done to override these variables for the
> documentation
> part of the build?
>
> Gunnar
>
> On Wed, Jul 6, 2016 at 4:29 PM, Steve Varnau <st...@esgyn.com>
> wrote:
>
> > Gunnar,
> >
> > Yes, that makes sense to me.
> >
> > Either that, or the docs could use only the major/minor numbers of the
> > release -- at least for the directory path where to generate the docs.
> > We
> > probably want the update number in the docs, but only want one version
> > per
> > minor release.
> >
> > docs/${TRAFODION_VER_MAJOR}.${TRAFODION_VER_MINOR}
> >
> > --Steve
> >
> >
> > > -----Original Message-----
> > > From: Gunnar Tapper [mailto:tapper.gunnar@gmail.com]
> > > Sent: Wednesday, July 6, 2016 3:09 PM
> > > To: dev@trafodion.incubator.apache.org
> > > Subject: [DISCUSS] Documentation Versioning
> > >
> > > Hi,
> > >
> > > I noticed that Steve 2.0.x header for the documentation. I think this
> > > is
> > > preferable.
> > >
> > > However, I know that we want to move to a model where the
> documentation
> > > update is part of the release rather than done against the master post
> > > release.
> > >
> > > The current scheme is that we place documentation in a latest
> > > directory
> > as
> > > well as a versioned directory. This means that you have to; for
> > > example,
> > > build 2.0.x documents setting $TRAFODION_VER to "2.0.0" to ensure that
> > the
> > > documents are placed on the correct versioned directory. The result
> > > will
> > > be
> > > that the version-dependent documents are placed in
> > > http://trafodion.apache.org/docs/2.0.0/*.
> > >
> > > Moving forward, I think it'd be better if we create a $DOCS_VER or
> > > something like that to allow for dot releases without having to create
> > dot
> > > releases of the documentation.
> > >
> > > Thoughts?
> > >
> > > --
> > > Thanks,
> > >
> > > Gunnar
> > > *If you think you can you can, if you think you can't you're right.*
> >
>
>
>
> --
> Thanks,
>
> Gunnar
> *If you think you can you can, if you think you can't you're right.*
Re: [DISCUSS] Documentation Versioning
Posted by Gunnar Tapper <ta...@gmail.com>.
Hi Steve,
From what I see, these variables are defined in core/sqf/sqenvcom.sh.
However, TRAFODION_VER_MINOR is set to 1 in the main branch already. That
works once the documentation updates are done as part of the release rather
than post release as today.
For now, what can be done to override these variables for the documentation
part of the build?
Gunnar
On Wed, Jul 6, 2016 at 4:29 PM, Steve Varnau <st...@esgyn.com> wrote:
> Gunnar,
>
> Yes, that makes sense to me.
>
> Either that, or the docs could use only the major/minor numbers of the
> release -- at least for the directory path where to generate the docs. We
> probably want the update number in the docs, but only want one version per
> minor release.
>
> docs/${TRAFODION_VER_MAJOR}.${TRAFODION_VER_MINOR}
>
> --Steve
>
>
> > -----Original Message-----
> > From: Gunnar Tapper [mailto:tapper.gunnar@gmail.com]
> > Sent: Wednesday, July 6, 2016 3:09 PM
> > To: dev@trafodion.incubator.apache.org
> > Subject: [DISCUSS] Documentation Versioning
> >
> > Hi,
> >
> > I noticed that Steve 2.0.x header for the documentation. I think this is
> > preferable.
> >
> > However, I know that we want to move to a model where the documentation
> > update is part of the release rather than done against the master post
> > release.
> >
> > The current scheme is that we place documentation in a latest directory
> as
> > well as a versioned directory. This means that you have to; for example,
> > build 2.0.x documents setting $TRAFODION_VER to "2.0.0" to ensure that
> the
> > documents are placed on the correct versioned directory. The result will
> > be
> > that the version-dependent documents are placed in
> > http://trafodion.apache.org/docs/2.0.0/*.
> >
> > Moving forward, I think it'd be better if we create a $DOCS_VER or
> > something like that to allow for dot releases without having to create
> dot
> > releases of the documentation.
> >
> > Thoughts?
> >
> > --
> > Thanks,
> >
> > Gunnar
> > *If you think you can you can, if you think you can't you're right.*
>
--
Thanks,
Gunnar
*If you think you can you can, if you think you can't you're right.*
RE: [DISCUSS] Documentation Versioning
Posted by Steve Varnau <st...@esgyn.com>.
Gunnar,
Yes, that makes sense to me.
Either that, or the docs could use only the major/minor numbers of the
release -- at least for the directory path where to generate the docs. We
probably want the update number in the docs, but only want one version per
minor release.
docs/${TRAFODION_VER_MAJOR}.${TRAFODION_VER_MINOR}
--Steve
> -----Original Message-----
> From: Gunnar Tapper [mailto:tapper.gunnar@gmail.com]
> Sent: Wednesday, July 6, 2016 3:09 PM
> To: dev@trafodion.incubator.apache.org
> Subject: [DISCUSS] Documentation Versioning
>
> Hi,
>
> I noticed that Steve 2.0.x header for the documentation. I think this is
> preferable.
>
> However, I know that we want to move to a model where the documentation
> update is part of the release rather than done against the master post
> release.
>
> The current scheme is that we place documentation in a latest directory as
> well as a versioned directory. This means that you have to; for example,
> build 2.0.x documents setting $TRAFODION_VER to "2.0.0" to ensure that the
> documents are placed on the correct versioned directory. The result will
> be
> that the version-dependent documents are placed in
> http://trafodion.apache.org/docs/2.0.0/*.
>
> Moving forward, I think it'd be better if we create a $DOCS_VER or
> something like that to allow for dot releases without having to create dot
> releases of the documentation.
>
> Thoughts?
>
> --
> Thanks,
>
> Gunnar
> *If you think you can you can, if you think you can't you're right.*