Planning

[Thomas Fox <Th...@seitenbau.net>]

As we're now past the 4.0-beta1 release, it's worth while to put a few
thoughts into what comes next. There have been a few discussion issues open
from the 4.0-beta1 release, as well as a general requirement from apache
infrastructure.

1) It is still undecided whether we want to include documentation with the
binary releases. Currently they only contain the jar and their
dependencies.
2) It is also undecided whether we want to provide source packages for the
single modules.
3) We need to switch the site publishing mechanism to svnpubsub until the
end of year [1]. So some change in the site publishing mechanism is needed.
We need to consider the following:
  - We need a location for the site in svn (currently the "default
location" db/torque/site is occupied by the torque 3 site project, see also
(5))
  - We probably want to retain the documentation for older releases
  - It should be no hassle to create a new site version directory (as we
now have for the old docs of 3.1, 3.2, and the new 4.0 but not the current
3.3 docs)
4) How much time do we allow for testing before the first attempt to
release 4.0 ?
5) Do we want to reorganize svn by putting the torque 3 resources into
aseparate place ?
6) I'd like to improve the online docs further by dropping the strict
separation between modules in the docs.

My personal opinions are:
1) We should create a README file for the binary distributions, pointing to
the online documentation. As the modules are too much connected, creating
documentation for a single module is very much hassle (and cannot be taken
from the online docs). Including docs for all the modules will probably
confuse an innocent user.
2) I do not see the necessity to have a source distribution for single
modules. We already have a source distribution for all modules. Having
single source distributions has the problem that the module builds depend
on each other.
3) We can use db/torque/site-svnpubsub as svn location. There, a directory
should exist for every documentation version we want to retain (even the
newest version), e.g db/torque/site-svnpubsub/torque-4.0. There should be a
single index.html file in the db/torque/site-svnpubsub location, which
redirects to the current version.
4) I'd suggest two months. So try starting to release 4.0 end of November.
5) Reorganizing would break existing svn locations. But as long as we edit
the site accordinglis, this should not be a problem. I suggest to create a
torque3 directory along the torque4 directory (db/torque/torque3) and move
the torque 3 stuff in there.
6) In my opinion, the user sees Torque as a single toolkit. Why should he
bother to first think into which module he must look into for
documentation? While at this, I'd also like to move the docs to a more
prominent place than Module Documentation/Modules/${module}/Reference in
the current site menu structure

Any opinions / suggestions / vetos ?

     Thomas

[1] http://www.apache.org/dev/project-site.html#svnpubsub


---------------------------------------------------------------------
To unsubscribe, e-mail: torque-dev-unsubscribe@db.apache.org
For additional commands, e-mail: torque-dev-help@db.apache.org

RE: Planning

[Thomas Fox <Th...@seitenbau.net>]

Greg Monroe wrote:

> > 1) It is still undecided whether we want to include documentation with
the
> >    binary releases. Currently they only contain the jar and their
> >    dependencies.
>
> AFAIK, there is no requirement for this. I do think it's important for
folks
> to be able to be able to access offline docs for a specific version. But
the
> binary jars does not seem to be the right place for this. I'd say that
there
> docs should be in the source or a separate download and the binary distro
> readme should point to where they can be downloaded.

Ok, I'll see what I can do. Not sure how this would complicate the build
process. I'll have a look.
https://issues.apache.org/jira/browse/TORQUE-237

>...
> > 3) We need to switch the site publishing mechanism to svnpubsub until
the
> >    end of year [1]. So some change in the site publishing mechanism is
> >    needed. We need to consider the following:
> >  - We need a location for the site in svn (currently the "default
> location"
> >    db/torque/site is occupied by the torque 3 site project, see also
(5))
> >  - We probably want to retain the documentation for older releases
> >  - It should be no hassle to create a new site version directory (as we
now
> >    have for the old docs of 3.1, 3.2, and the new 4.0 but not the
current
> >    3.3 docs)
>
> The strategy Thomas F proposes seems OK. E.g. site-svnpubsub with subdirs
for
> each release. Maybe scm-site or site-scm would be a shorter name?

I have now used site-scmpublish as a temporary name. It seems, however,
that the final location will be at
https://svn.apache.org/repos/infra/websites/production/db/torque, so this
directory will go away.

> ...
> BTW - Did any notices of the beta release go out?  E.g. in the site news
and
> to torque-users?  If folks don't know it's there, they probably won't
test
> with their local code.

Yes, there were messages sent to the dev and user lists, as well as an
announcement on the news page on the torque web site..

> > 5) Do we want to reorganize svn by putting the torque 3 resources into
a
> >    separate place ?
>
> +1... but we should make sure it's well noted in the site.  This means
> that folks with local projects that pull from svn will need to update
> their local settings.  When such stuff breaks, it should be easy to find
> a notice that the structure has changed.
>
> Maybe there should be some "pre-notices" too.  E.g, a note on the site,
> to this list, and to torque-user that the svn structure will change on
> a specific date (or date range).

ok, will do that.

>
> > 6) I'd like to improve the online docs further by dropping the strict
> >    separation between modules in the docs.
>
> +1 - I think this would allow for some needed overview and "rabbit trail"
> type organization.  E.g., what to read to understand using torque
> vs what to read for modifying/developing topics.
>
> I think we sort of have this now, but you have to understand which
> sub-project you need... which you don't until you start learning things.
Lol.

Yes, this is one of the problems I'd like to adress.

   Thomas


---------------------------------------------------------------------
To unsubscribe, e-mail: torque-dev-unsubscribe@db.apache.org
For additional commands, e-mail: torque-dev-help@db.apache.org

RE: Planning

[Greg Monroe <Gr...@dukece.com>]

> 1) It is still undecided whether we want to include documentation with the
>    binary releases. Currently they only contain the jar and their 
>    dependencies.

AFAIK, there is no requirement for this. I do think it's important for folks
to be able to be able to access offline docs for a specific version. But the
binary jars does not seem to be the right place for this. I'd say that there
docs should be in the source or a separate download and the binary distro
readme should point to where they can be downloaded. 

> 2) It is also undecided whether we want to provide source packages for the
>    single modules.

The requirements in www.apache.org/dev/release.html says: 

... must contain a source package, which must be sufficient for a user to 
build and test the release..

Unless we plan to change our release/versioning process to allow for different
versions of sub modules, I think the single all in one source is fine.
 
> 3) We need to switch the site publishing mechanism to svnpubsub until the
>    end of year [1]. So some change in the site publishing mechanism is 
>    needed. We need to consider the following:
>  - We need a location for the site in svn (currently the "default location"   
>    db/torque/site is occupied by the torque 3 site project, see also (5))
>  - We probably want to retain the documentation for older releases
>  - It should be no hassle to create a new site version directory (as we now 
>    have for the old docs of 3.1, 3.2, and the new 4.0 but not the current
>    3.3 docs)

The strategy Thomas F proposes seems OK. E.g. site-svnpubsub with subdirs for
each release. Maybe scm-site or site-scm would be a shorter name?

> 4) How much time do we allow for testing before the first attempt to release
>    4.0 ?

4.0 is a major change.  I think folks will be a bit slow to start kicking 
the tires due to the learning curve.  2 months might be enough, but I don't
think we'd really get a lot of extra testers in that time frame.  

On the other hand, if stuff pops up after 4.0 is released, it seems like all
the good work done to automate the release process would make it easier to
do a 4.1 with fixes.

I think as long as we know there wouldn't be too many months between
missing features reports (e.g. I used to be able to do..) and a release
that corrects them, a short 2 month test time is OK.

BTW - Did any notices of the beta release go out?  E.g. in the site news and
to torque-users?  If folks don't know it's there, they probably won't test 
with their local code.


> 5) Do we want to reorganize svn by putting the torque 3 resources into a
>    separate place ?

+1... but we should make sure it's well noted in the site.  This means
that folks with local projects that pull from svn will need to update
their local settings.  When such stuff breaks, it should be easy to find
a notice that the structure has changed.

Maybe there should be some "pre-notices" too.  E.g, a note on the site,
to this list, and to torque-user that the svn structure will change on
a specific date (or date range).

> 6) I'd like to improve the online docs further by dropping the strict 
>    separation between modules in the docs.

+1 - I think this would allow for some needed overview and "rabbit trail"
type organization.  E.g., what to read to understand using torque 
vs what to read for modifying/developing topics. 

I think we sort of have this now, but you have to understand which 
sub-project you need... which you don't until you start learning things. Lol.

DukeCE Privacy Statement:
Please be advised that this e-mail and any files transmitted with
it are confidential communication or may otherwise be privileged or
confidential and are intended solely for the individual or entity
to whom they are addressed. If you are not the intended recipient
you may not rely on the contents of this email or any attachments,
and we ask that you please not read, copy or retransmit this
communication, but reply to the sender and destroy the email, its
contents, and all copies thereof immediately. Any unauthorized
dissemination, distribution or copying of this communication is
strictly prohibited.

---------------------------------------------------------------------
To unsubscribe, e-mail: torque-dev-unsubscribe@db.apache.org
For additional commands, e-mail: torque-dev-help@db.apache.org

Re: Planning

[Thomas Fox <Th...@seitenbau.net>]

Thomas Vandahl wrote:
> On 03.10.12 03:21, Thomas Fox wrote:
> > 2) I do not see the necessity to have a source distribution for single
> > modules. We already have a source distribution for all modules. Having
> > single source distributions has the problem that the module builds
depend
> > on each other.
>
> I already expressed my opinion that this is a bit uncommon. It would at
> least not meet my expectations.

I'm not totally opposed to it, it just makes the build more complicated and
is work to implement. If you find it is necessary, please feel free to go
ahead and implement it.

> > 3) We can use db/torque/site-svnpubsub as svn location. There, a
directory
> > should exist for every documentation version we want to retain (even
the
> > newest version), e.g db/torque/site-svnpubsub/torque-4.0. There should
be a
> > single index.html file in the db/torque/site-svnpubsub location, which
> > redirects to the current version.
>
> I just noticed that a Maven plugin has been released to handle this. See
> here: http://maven.apache.org/sandbox/plugins/maven-scm-publish-plugin/
> We should check if the plugin meets the requirements.

Thanks for the heads-up, I'll try to use it.

> Concerning the maintenance of old docs: I'd drop this for 3.1 and 3.2,
> only keeping 3.3.

ok, fine with me.
So the first step would be to recreate the 3.3 docs without the reference
to the 3.2 and 3.1 docs and check them in
For the 4.0 docs, I'm going to try and check them in using the
maven-scm-publish-plugin (already without the cobertura reports, saves 70M
disk space).
After this has happend, we'll review the checked-in site and then ask intra
to set up svnpubsub.
Any objections ?

> ...
> > 6) In my opinion, the user sees Torque as a single toolkit. Why should
he
> > bother to first think into which module he must look into for
> > documentation? While at this, I'd also like to move the docs to a more
> > prominent place than Module Documentation/Modules/${module}/Reference
in
> > the current site menu structure
>
> I believe that most people only get in touch with the maven-plugin and
> the runtime. Fiddling with the generator and the templates is advanced
> stuff, IMO. (Do we have some numbers to prove this?) I guess a more
> prominent place for the docs could do no harm. I'd concentrate on the
> most-used parts, however.

Yes, that would be the main feature to consider.

> PS: Do we meet in Sinsheim?

I'm afraid not. Lots to do with my two small kids...


---------------------------------------------------------------------
To unsubscribe, e-mail: torque-dev-unsubscribe@db.apache.org
For additional commands, e-mail: torque-dev-help@db.apache.org

Re: Planning

[Thomas Vandahl <tv...@apache.org>]

On 03.10.12 03:21, Thomas Fox wrote:
> 2) I do not see the necessity to have a source distribution for single
> modules. We already have a source distribution for all modules. Having
> single source distributions has the problem that the module builds depend
> on each other.

I already expressed my opinion that this is a bit uncommon. It would at
least not meet my expectations.

> 3) We can use db/torque/site-svnpubsub as svn location. There, a directory
> should exist for every documentation version we want to retain (even the
> newest version), e.g db/torque/site-svnpubsub/torque-4.0. There should be a
> single index.html file in the db/torque/site-svnpubsub location, which
> redirects to the current version.

I just noticed that a Maven plugin has been released to handle this. See
here: http://maven.apache.org/sandbox/plugins/maven-scm-publish-plugin/
We should check if the plugin meets the requirements.

Concerning the maintenance of old docs: I'd drop this for 3.1 and 3.2,
only keeping 3.3.

> 4) I'd suggest two months. So try starting to release 4.0 end of November.

+1

> 5) Reorganizing would break existing svn locations. But as long as we edit
> the site accordinglis, this should not be a problem. I suggest to create a
> torque3 directory along the torque4 directory (db/torque/torque3) and move
> the torque 3 stuff in there.

+1

> 6) In my opinion, the user sees Torque as a single toolkit. Why should he
> bother to first think into which module he must look into for
> documentation? While at this, I'd also like to move the docs to a more
> prominent place than Module Documentation/Modules/${module}/Reference in
> the current site menu structure

I believe that most people only get in touch with the maven-plugin and
the runtime. Fiddling with the generator and the templates is advanced
stuff, IMO. (Do we have some numbers to prove this?) I guess a more
prominent place for the docs could do no harm. I'd concentrate on the
most-used parts, however.

Bye, Thomas.

PS: Do we meet in Sinsheim?


---------------------------------------------------------------------
To unsubscribe, e-mail: torque-dev-unsubscribe@db.apache.org
For additional commands, e-mail: torque-dev-help@db.apache.org