You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@subversion.apache.org by kf...@collab.net on 2003/07/15 15:38:50 UTC
Re: [PATCH] notes/releases.txt
This patch is a great idea, Paul, thanks for doing it. Some minor
edits below, for your consideration:
> + a. Create the branch
> +
> + svn cp -rHEAD -m"Create release-X.YY.Z branch" \
> + http://svn.collab.net/repos/svn/trunk \
> + http://svn.collab.net/repos/svn/branches/release-X.YY.Z
> +
> +
> + (Note that only the release manager commits to the branch;
> + everyone else continues working on trunk, and the release
> + manager ports changes across only if absolutely necessary.)
> +
> +
> + b. Check out a working copy of the branch
> +
> + svn co http://svn.collab.net/repos/svn/branches/release-X.YY.Z
> +
> + or
> +
> + svn switch http://svn.collab.net/repos/svn/branches/release-X.YY.Z
> +
> + if you have an existing working copy
Excellent! No comment :-).
> + c. Make sure your release branch wc has the following packages
> + extracted into the root of the wc tree:
> +
> + apr (http://www.apache.org)
> + apr-util (http://www.apache.org)
> + neon (http://www.webdav.org)
Are there more specific URLs for these? If so, giving them here can
save time (or just point to INSTALL, if they're in there).
> + DocBook Tools (see doc/book/README for where/how to install these)
> + XSL Style Sheets (docbook-xsl)
> + http://sourceforge.net/project/showfiles.php?group_id=21935
> +
> + FOP http://xml.apache.org/fop/index.html
> +
> + *ALL* of these are needed to build Subversion.
Are these URLs given in some other document? If so, just point to
that doc, IMHO. That way if we fix it in one place, it's fixed for
all the others.
> + Subversion usually develops against the latest release of the
> + Apache 2.x web server. Therefore, the easiest way to get
> + apr/apr-util is to download the latest release of the httpd
> + source, and use the apr/apr-util trees contained within.
> +
> + $ tar zxvf httpd-2.x.yy.tar.gz
> + $ cd httpd-2.x.yy/srclib
> + $ rsync -rav apr apr-util /path/to/release-X.YY.Z
> +
> + Extract the neon source tar-ball to the same location.
> +
> + Configure httpd-2.x.yy:
> +
> + ./configure --prefix=/path/to/dev/area --enable-so --enable-dav
> + --enable-deflate [--enable-maintainer-mode]
> +
> + make
> + make install
This is all explained in INSTALL, right? Maybe just reference that.
Basically, release managers have to be familiar with installing
Subversion and running all combinations of 'make check'. They might
as well get that familiarity the same way everyone else does, reading
the same docs, etc...
> + Make sure httpd.conf is properly set up for DAV access:
> +
> + <Location /repositories>
> + DAV svn
> + SVNParentPath /path/to/new_release-X.YY.Z/subversion\
> + /tests/clients/cmdline/repositories
> + </Location>
> +
> + <Location /local_tmp/repos>
> + DAV svn
> + SVNPath /path/to/new_release-X.YY.Z/subversion\
> + /tests/clients/cmdline/local_tmp/repos
> + </Location>
This is also a dup of information in INSTALL. Just reference it.
> + d. Run ./autogen.sh
Maybe most of the above could be compressed to
"See sections 'Building the Latest Source under Unix' and 'BUILDING
A SUBVERSION SERVER' in the INSTALL file."
:-).
> 4. Run './dist.sh [ARGS ...]' (see dist.sh for details about ARGS)
> Watch dist.sh's output to make sure everything goes smoothly; when
> it's done, you'll have 'subversion-BLAH.tar.gz' in the cwd.
Beautiful.
> @@ -20,33 +87,101 @@
> 5. Test the tarball:
> a) tar xfz subversion-rXXXX.tar.gz; cd subversion-rXXXX
> b) ./configure --disable-shared --enable-maintainer-mode
> +
> + ./configure --prefix=/path/to/dev/area
> + --enable-mod-activation
> + --with-apxs=/path/to/apache/bin/apxs
> + --enable-maintainer-mode
Don't say how to build Subversion, INSTALL already says it :-).
> c) make
> d) make check
> - e) (start up Apache for testing, then) make davcheck
> - f) (start up svnserve for testing, then) make svncheck
> - g) subversion/clients/cmdline/svn co http://svn.collab.net/repos/svn/trunk
> + e) make install (this activates mod_dav)
> + e) make davcheck
Likewise, more or less.
> -6. [OPTIONAL] Upgrade svn.collab.net to head, then repeat step 5e.
> - Someone with administrative access should do this, usually not the
> - release manager.
> + For this, start up Apache after having configured according to
> + the directions in subversion/tests/client/cmdline/README
> +
> + f) make svncheck
>
> + For this step, start up svnserve with special args:
> +
> + $ subversion/svnserve/svnserve -d -r \
> + `pwd`/subversion/tests/clients/cmdline
> +
> + After svnserve is running as a daemon 'make svncheck' should run
> +
> + g) Then test that you can check out the subversion repository
> + with this environment:
> +
> + subversion/clients/cmdline/svn co \
> + http://svn.collab.net/repos/svn/trunk
I don't know if this material is already in INSTALL, but perhaps it
should be? The point is, testing is not something only release
managers do...
> 7. Post tarball to the "File sharing" section of the tigris.org web
> - site <http://subversion.tigris.org/servlets/ProjectDownloadList>.
> + site <http://subversion.tigris.org/servlets/ProjectDownloadList>:
> +
> The ability to upload a public, automatically approved tarball
> requires the "Project Document - Approve" permission, which is a
> standard part of the "Download Manager" or "Content Developer"
> - roles.
> + roles. If you don't have this access, make sure you
> + 'Request a New Role' from the tigris web site.
Great!
> -8. Move branch into the tags directory in the repository. Now that
> - the release is public, no more changes can happen on that branch.
> - If we discover problems with the release, then we make a new branch
> - (with the minor version number incremented), apply fixes, and go
> - through the release process again.
> + Once Download Manager status has been granted:
>
> -9. Update www/project_status.html on trunk, including a MD5 checksum
> - for the fresh tarball. Commit.
> + - Log into http://subversion.tigris.org
> + - Click on the 'file sharing' link (left frame at the top)
> + - Click on the 'Source tarballs' link (main frame)
> + - Click on the 'Add a file' link (top, main frame, under 'File Sharing')
> + - Fill in the following fields:
>
> + Name: subversion-X.YY.Z.tar.gz (replace X.YY.Z with the release number)
> + Status: Stable
> + Description: Subversion release 0.25.0 (MD5: <md5sum of tarball>)
> + Contents: (select 'Attachment', hit Browse or enter path to tarball)
> +
> + - Click Submit
Beautiful...
> + To get the MD5 checksum for the tarball, make sure you have the
> + md5sum command installed and from the release branch wc, run:
> +
> + md5sum subversion-X.YY.Z.tar.gz
> +
> + There will be a single line of 2 fields returned looking something like:
> +
> + $ md5sum subversion-0.25.tar.gz
> + a018220d5c790161bc712ccb7d0f1b38 subversion-0.25.tar.gz
> +
> + The 32 character alpha-numeric string on the left is the checksum.
> + Use this in the Description field, and also mention it in the
> + Announcement e-mail explained below.
Very detailed, but probably a good idea to spell it out like this, yes.
> +8. Move branch into the tags directory in the repository.
> +
> + svn mv mv http://svn.collab.net/repos/svn/branches/release-X.YY.Z \
> + http://svn.collab.net/repos/svn/tags/X.YY.Z \
> + -m"Moved Release X.YY.Z branch to tags/"
> +
> + Now that the release is public, no more changes can happen on that
> + branch. If we discover problems with the release, then we make a
> + new branch (with the minor version number incremented), apply
> + fixes, and go through the release process again.
Nice description.
> +9. Update www/project_status.html on trunk.
> +
> + Edit the www/project_status.html file appropriately in /trunk *NOT*
> + in the release branch and commit.
> +
> + Then, go to http://svn.collab.net and click on the "Update the live
> + web site" link. Click 'Publish' then visit
> + http://subversion.tigris.org/project_status.html to make sure the
> + changes are there. You may have to hit 'Reload' if this page was
> + previously visited, and therefore cached by your browser.
> +
Good.
> +
> +12. [OPTIONAL] Upgrade svn.collab.net to head, then repeat step 5e.
> + Someone with administrative access should do this, usually not the
> + release manager.
Good point, that had been confusing, yes.
-Karl
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: [PATCH] notes/releases.txt
Posted by Paul L Lussier <pl...@lanminds.com>.
In a message dated: 15 Jul 2003 10:38:50 CDT
kfogel@collab.net said:
>> + Make sure httpd.conf is properly set up for DAV access:
>> +
>> + <Location /repositories>
>> + DAV svn
>> + SVNParentPath /path/to/new_release-X.YY.Z/subversion\
>> + /tests/clients/cmdline/repositories
>> + </Location>
>> +
>> + <Location /local_tmp/repos>
>> + DAV svn
>> + SVNPath /path/to/new_release-X.YY.Z/subversion\
>> + /tests/clients/cmdline/local_tmp/repos
>> + </Location>
>
>This is also a dup of information in INSTALL. Just reference it.
Actually, this is buried in subversion/tests/clients/cmdline/README,
to which I now point.
>Maybe most of the above could be compressed to
>
> "See sections 'Building the Latest Source under Unix' and 'BUILDING
> A SUBVERSION SERVER' in the INSTALL file."
I added this text.
>Don't say how to build Subversion, INSTALL already says it :-).
>
>> c) make
>> d) make check
>> - e) (start up Apache for testing, then) make davcheck
>> - f) (start up svnserve for testing, then) make svncheck
>> - g) subversion/clients/cmdline/svn co http://svn.collab.net/repos/svn/t
>runk
>> + e) make install (this activates mod_dav)
>> + e) make davcheck
>
>Likewise, more or less.
Actually, I could find no documentation on running the various tests,
with the exception of a very brief mention in
subversion/tests/clients/cmdline/README.
>> + f) make svncheck
>>
>> + For this step, start up svnserve with special args:
>> +
>> + $ subversion/svnserve/svnserve -d -r \
>> + `pwd`/subversion/tests/clients/cmdline
>> +
>> + After svnserve is running as a daemon 'make svncheck' should run
>> +
>> + g) Then test that you can check out the subversion repository
>> + with this environment:
>> +
>> + subversion/clients/cmdline/svn co \
>> + http://svn.collab.net/repos/svn/trunk
>
>I don't know if this material is already in INSTALL, but perhaps it
>should be? The point is, testing is not something only release
>managers do...
None of this information is really documented anywhere. The svnserve
example was found in the toplevel Makefile. IMO, not the optimal
location for it :)
I'll be posting a new patch based on these changes shortly.
--
Seeya,
Paul
--
Key fingerprint = 1660 FECC 5D21 D286 F853 E808 BB07 9239 53F1 28EE
It may look like I'm just sitting here doing nothing,
but I'm really actively waiting for all my problems to go away.
If you're not having fun, you're not doing it right!
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: [PATCH] notes/releases.txt
Posted by kf...@collab.net.
Greg Stein <gs...@lyra.org> writes:
> > I'd like to propose:
> >
> > mv notes/releases.txt trunk/RELEASING
>
> I see no reason to move that up a level. Most users just aren't going to
> want or need to read that.
I think the idea was that things in notes/ are (supposedly) documents
in the process of being solidified. Once they're bronzed, they get
moved to a more permanent place.
But I'm not sure I buy this philosophy of the notes/ area, now that I
think about it. I think Greg is right: leave the top level for things
that are of interest to many people, and notes/ for things of interest
only to individuals or small groups.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: [PATCH] notes/releases.txt
Posted by Greg Stein <gs...@lyra.org>.
On Tue, Jul 15, 2003 at 05:04:56PM -0400, Paul L Lussier wrote:
>...
> I'd like to propose:
>
> mv notes/releases.txt trunk/RELEASING
I see no reason to move that up a level. Most users just aren't going to
want or need to read that.
Cheers,
-g
--
Greg Stein, http://www.lyra.org/
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: [PATCH] notes/releases.txt
Posted by Steve Williams <sl...@internode.on.net>.
> I suggest that under BUILD REQUIREMENTS we add a Dependencies subsection
> which only lists the required external packages, their current rev
> numbers, and their URLs. Section II. can pretty much remain the
> same, with the exception that the rev numbers would be removed.
>
> How does that sound?
That sounds a lot like the idiot's guide (for want of a better term) I've
made for myself while trying to get the Subversion 0.25.0 RPMs installed on
RH9. I've got the URLs for the specific versions of required modules and
the exact command-lines required to install them (since they all seem to be
different). So now I can easily and quickly setup a brand new RH9 machine
and get Subversion 0.25.0 installed with no fuss.
Sly
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: [PATCH] notes/releases.txt
Posted by kf...@collab.net.
pll@lanminds.com writes:
> So, I went looking at subversion/tests/README and
> subversion/tests/clients/cmdline/README. Interestingly, neither one
> really seems to be about how to test subversion. They both seem to be
> more about how to write tests than actually running tests; the first
> in C and the second in Python, which then references the first.
> (though, the C doc outlines the correct UI for tests, and the
> Python doc gives some good examples of the UI in action).
>
> Should these documents be combined into a more general TESTING
> document with sections for "Running Tests" and "Writing Tests"?
>
> (again, I'm good at not doing stuff, so, if this too is undesirable,
> just say so, and I'll leave them alone :)
In my opinion, improvement is not likely to result from this process,
and the docs should just be left alone...
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: [PATCH] notes/releases.txt
Posted by pl...@lanminds.com.
In a message dated: 15 Jul 2003 19:37:51 CDT
kfogel@collab.net said:
>Paul, I think you're trying to tune the docs so they're optimized for
>release management.
I don't think that's the case, but it seems to be the perception I'm
giving everyone :) In my mind, I'm trying to tune the docs so that
essential information is quickly and easily obtained, and centralized
in as few locations as possible. But, if that's not desirable, I'm
very good at not doing things :)
>The INSTALL file is very easy to complain about, but not so easy to
>improve. Writing documentation is hard.
I agree with that wholeheartedly!
Now, on to something completely different, yet related...
You said at some point:
kfogel> Don't say how to build Subversion, INSTALL already says it :-).
pll> c) make
pll> d) make check
pll> - e) (start up Apache for testing, then) make davcheck
pll> - f) (start up svnserve for testing, then) make svncheck
pll> - g) subversion/clients/cmdline/svn co http://svn.collab.net/repos/svn/trunk
pll> + e) make install (this activates mod_dav)
pll> + e) make davcheck
kfogel> Likewise, more or less.
I take that to mean that 'make check', and running the other tests are,
more or less, documented elsewhere. INSTALL mentions 'make check' and
'make install', but has no further comment other than to list them
as I did above.
'make davcheck' isn't mentioned anywhere else but releases.txt AFAICT.
At some point, there seemed to be a concensus for a TESTING file,
outlining how to test Subversion (did I misinterpret this?).
So, I went looking at subversion/tests/README and
subversion/tests/clients/cmdline/README. Interestingly, neither one
really seems to be about how to test subversion. They both seem to be
more about how to write tests than actually running tests; the first
in C and the second in Python, which then references the first.
(though, the C doc outlines the correct UI for tests, and the
Python doc gives some good examples of the UI in action).
Should these documents be combined into a more general TESTING
document with sections for "Running Tests" and "Writing Tests"?
(again, I'm good at not doing stuff, so, if this too is undesirable,
just say so, and I'll leave them alone :)
--
Seeya,
Paul
--
Key fingerprint = 1660 FECC 5D21 D286 F853 E808 BB07 9239 53F1 28EE
It may look like I'm just sitting here doing nothing,
but I'm really actively waiting for all my problems to go away.
If you're not having fun, you're not doing it right!
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: [PATCH] notes/releases.txt
Posted by kf...@collab.net.
pll@lanminds.com writes:
> >Mmm, not so sure about that. We already have autogen.sh checking for
> >these, and INSTALL documenting them... and INSTALL is the right place,
> >because these dependencies are needed to, well, install Subversion
> >:-). Let's leave them there.
>
> What about a location closer to the top of the INSTALL file which
> simply does what I wanted the DEPENDENCIES file for.
>
> My goal is to make it quick and painless to find out what revs of
> what external dependencies are required, and where to get them, as
> well as painless to maintain the this list.
>
> As it is now, even though they are listed in INSTALL, you have to
> scroll through a good portion of the file just to find out what you
> need to install in order to build Subversion.
That's because one might not need/want to build the server. Of
course, someone rolling a dist always needs those dependencies, but in
the long run most users just need to build a client (so they don't
need, for example, Berkeley DB). Plus, people bootstrapping from a
tarball don't need to fetch any dependencies, so listing deps
prominently in INSTALL would be just so much noise for those
people... Or worse, they'll see the list and waste time fetching all
that stuff, only to discover they didn't need it.
Paul, I think you're trying to tune the docs so they're optimized for
release management. Please don't do that :-). Instead, tune the
release manager to work with information whose presentation was
designed for non release managers.
The INSTALL file is very easy to complain about, but not so easy to
improve. Writing documentation is hard. I actually think the INSTALL
file does a pretty good job of covering a complex subject. It's like
complaining to the IRS that the tax forms are confusing -- they're
pretty well-designed, actually, it's the tax *law* that's inherently
confusing, but changing that is a much bigger task.
-K
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: [PATCH] notes/releases.txt
Posted by pl...@lanminds.com.
In a message dated: 15 Jul 2003 16:07:26 CDT
kfogel@collab.net said:
>Paul L Lussier <pl...@lanminds.com> writes:
>> and adding a DEPENDENCIES listing just external packages,
>> version numbers, and URLs. This document would then be reference by
>> all other docs where necessary. It would also be the only place
>> where version numbers are mentioned.
>> to start.
>
>Mmm, not so sure about that. We already have autogen.sh checking for
>these, and INSTALL documenting them... and INSTALL is the right place,
>because these dependencies are needed to, well, install Subversion
>:-). Let's leave them there.
What about a location closer to the top of the INSTALL file which
simply does what I wanted the DEPENDENCIES file for.
My goal is to make it quick and painless to find out what revs of
what external dependencies are required, and where to get them, as
well as painless to maintain the this list.
As it is now, even though they are listed in INSTALL, you have to
scroll through a good portion of the file just to find out what you
need to install in order to build Subversion.
The current INSTALL TOC has:
I. BUILD REQUIREMENTS
II. INSTALLATION
A. Bootstrapping from a Tarball or RPM
B. Building the Latest Source under Unix
I suggest that under BUILD REQUIREMENTS we add a Dependencies subsection
which only lists the required external packages, their current rev
numbers, and their URLs. Section II. can pretty much remain the
same, with the exception that the rev numbers would be removed.
How does that sound?
--
Seeya,
Paul
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: [PATCH] notes/releases.txt
Posted by kf...@collab.net.
Paul L Lussier <pl...@lanminds.com> writes:
> I'd like to propose:
>
> mv notes/releases.txt trunk/RELEASING
> mv subversion/tests/clients/cmdline/README trunk/TESTING
Sounds good. Don't forget to check the new TESTING file for relative
references.
> and adding a DEPENDENCIES listing just external packages,
> version numbers, and URLs. This document would then be reference by
> all other docs where necessary. It would also be the only place
> where version numbers are mentioned.
> to start.
Mmm, not so sure about that. We already have autogen.sh checking for
these, and INSTALL documenting them... and INSTALL is the right place,
because these dependencies are needed to, well, install Subversion
:-). Let's leave them there.
> Next, I'd like to begin modifying HACKING, README, and INSTALL to
> properly cross-reference where necessary.
I think they pretty much already do, but sure, if you see trouble
spots, fix 'em.
> Is that reasonable/acceptable?
Sounds good to me...
-K
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: [PATCH] notes/releases.txt
Posted by Paul L Lussier <pl...@lanminds.com>.
In a message dated: 15 Jul 2003 14:56:26 CDT
kfogel@collab.net said:
>> Thoughts/comments?
>
>I think this is backwards.
Hmmm, yup. That's a thought :)
>The real issue here is the assumption that one can be "just" a release
>maintainer, without being familiar with building testing Subversion.
Well, I think there's a difference between 'building' Subversion, and
constantly maintaining a 'build environment'.
I've certainly built Subversion, but not as often as someone who's
constantly developing/hacking on it.
I was looking at this from my experience. I came in to this thinking
I understood what was needed. Mostly, there was nothing required to
perform the job of release manager I didn't understand, it was more a
matter of being able to find the correct information. Which I did,
but after searching in two or three locations. This is what I was
hoping to streamline.
>Sure, if some of those background documents are badly located or
>reduntant anyway, then they can be tweaked until better. But that's
>an independent issue, it has nothing to do with releases. There
>shouldn't be _any_ release-manager-specific tweaks necessary.
I can agree with that. How about I start taking a stab at these
diffent docs to get everything in line with each other?
I'd like to propose:
mv notes/releases.txt trunk/RELEASING
mv subversion/tests/clients/cmdline/README trunk/TESTING
and adding a DEPENDENCIES listing just external packages,
version numbers, and URLs. This document would then be reference by
all other docs where necessary. It would also be the only place
where version numbers are mentioned.
to start.
Next, I'd like to begin modifying HACKING, README, and INSTALL to
properly cross-reference where necessary.
And, I'll submit a patch for everything for approval :)
Is that reasonable/acceptable?
--
Seeya,
Paul
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: [PATCH] notes/releases.txt
Posted by kf...@collab.net.
pll@lanminds.com writes:
> The problem is that this same information is needed in several places.
> I found that to be true of a lot of information contained in
> releases.txt. So, the thought I has was, can certain pieces of
> information be coerced into m4 macros such that we can change it in 1
> place, but it gets updated everywhere it's needed?
>
> This would allow for having very explicit developer docs, while also
> providing for ease of maintenance of these docs. The only down side
> I can see is that in order to actually make use of these docs, you'd
> be required at the very least, to ./configure and make (though,
> perhaps we can create a new make target dev-docs?).
>
> Thoughts/comments?
I think this is backwards.
The real issue here is the assumption that one can be "just" a release
maintainer, without being familiar with building testing Subversion.
The release manager must be comfortable building Subversion, and
comfortable running the tests (including 'make svncheck' and 'make
davcheck'), same as any other developer. One acquires such knowledge
by reading the appropriate docs: INSTALL, subversion/testing/README,
etc. Ideally, the release manager is also comfortable building the
documentation in doc/book.
All these things are background knowledge the release manager is
presumed to have. Then notes/releases.txt describes the *remaining*
stuff, stuff that's specific to releasing but not to regular
installation or development (i.e., it's a delta against the background
knowledge).
Sure, if some of those background documents are badly located or
reduntant anyway, then they can be tweaked until better. But that's
an independent issue, it has nothing to do with releases. There
shouldn't be _any_ release-manager-specific tweaks necessary.
-Karl
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: [PATCH] notes/releases.txt
Posted by Paul L Lussier <pl...@lanminds.com>.
In a message dated: Tue, 15 Jul 2003 22:26:36 +0200
Lele Gaifax said:
>Why not ReST_ then? It's *very* readable and easy to write :-)
Probably because no one here has heard of it before now :)
--
Seeya,
Paul
--
Key fingerprint = 1660 FECC 5D21 D286 F853 E808 BB07 9239 53F1 28EE
It may look like I'm just sitting here doing nothing,
but I'm really actively waiting for all my problems to go away.
If you're not having fun, you're not doing it right!
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: [PATCH] notes/releases.txt
Posted by Lele Gaifax <le...@seldati.it>.
>>>>> Francois Beausoleil l'ha dit:
>> So, it comes down to a tradeoff between long-term information
>> management/maintenance and getting up to speed on release
>> management quickly.
Francois> Maybe the information in those files could/should be
Francois> HTML, then it becomes easy to refer to a part of the
Francois> document by using #whatever ?
Why not ReST_ then? It's *very* readable and easy to write :-)
ciao, lele.
.. _ReST http://docutils.sourceforge.net/docs/rst/
--
nickname: Lele Gaifax | Quando vivrò di quello che ho pensato ieri
real: Emanuele Gaifas | comincerò ad aver paura di chi mi copia.
email: lele@seldati.it | -- Fortunato Depero, 1929.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: [PATCH] notes/releases.txt
Posted by Francois Beausoleil <fb...@users.sourceforge.net>.
On Tue, 15 Jul 2003 12:47:35 -0400, pll@lanminds.com said:
[snip]
> kfogel> This is also a dup of information in INSTALL. Just
> kfogel> reference it.
>
> I wrestled with this back and forth for awhile. The problem I had
> was that even with the cross referencing, finding this information in
> the other docs quickly is rather a pain. I absolutely hate the idea
> of redundant data, but at the same time, it makes figuring out how to
> do a release more efficient. So, it comes down to a tradeoff between
> long-term information management/maintenance and getting up to speed
> on release management quickly.
Maybe the information in those files could/should be HTML, then it
becomes easy to refer to a part of the document by using #whatever ?
Just a suggestion...
>
> On one hand, had these steps been spelled out for me, I think the last
[snip]
Bye,
François
Developer of Java Gui Builder
http://jgb.sourceforge.net/
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: [PATCH] notes/releases.txt
Posted by pl...@lanminds.com.
>>>>> On 15 Jul 2003, "kfogel" == kfogel@collab.net wrote:
kfogel> This patch is a great idea, Paul, thanks for doing it.
My pleasure.
kfogel> Are there more specific URLs for these? If so, giving them
kfogel> here can save time (or just point to INSTALL, if they're in
kfogel> there).
I'll dig those up.
kfogel> Are these URLs given in some other document? If so, just
kfogel> point to that doc, IMHO. That way if we fix it in one
kfogel> place, it's fixed for all the others.
...
kfogel> This is all explained in INSTALL, right? Maybe just
kfogel> reference that.
...
kfogel> Basically, release managers have to be familiar with
kfogel> installing Subversion and running all combinations of 'make
kfogel> check'. They might as well get that familiarity the same
kfogel> way everyone else does, reading the same docs, etc...
...
kfogel> This is also a dup of information in INSTALL. Just
kfogel> reference it.
I wrestled with this back and forth for awhile. The problem I had
was that even with the cross referencing, finding this information in
the other docs quickly is rather a pain. I absolutely hate the idea
of redundant data, but at the same time, it makes figuring out how to
do a release more efficient. So, it comes down to a tradeoff between
long-term information management/maintenance and getting up to speed
on release management quickly.
On one hand, had these steps been spelled out for me, I think the last
release would have likely gone more quickly. On the other hand, I
wouldn't have learned nearly as much if they had. On the third hand,
I wouldn't have wasted nearly as much of yours and sussman's time :)
Perhaps what's needed is a review of the various INSTALL/BUILD/README
type docs which condenses the information into a more logical flow
that makes cross-referencing a little easier.
As you mentioned:
kfogel> these URLs given in some other document?
The problem is that this same information is needed in several places.
I found that to be true of a lot of information contained in
releases.txt. So, the thought I has was, can certain pieces of
information be coerced into m4 macros such that we can change it in 1
place, but it gets updated everywhere it's needed?
This would allow for having very explicit developer docs, while also
providing for ease of maintenance of these docs. The only down side
I can see is that in order to actually make use of these docs, you'd
be required at the very least, to ./configure and make (though,
perhaps we can create a new make target dev-docs?).
Thoughts/comments?
--
Seeya,
Paul
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org