1.6 release?

[Ryan Schmidt]

On Nov 11, 2007, at 23:14, Juan Manuel Palacios wrote:

> On Nov 6, 2007, at 8:36 PM, Simon Ruderich wrote:
>
>> On Tue, Nov 06, 2007 at 12:05:47PM -0800, markd at macports.org wrote:
>>
>>> Juan Manuel Palacios writes:
>>>
>>>> 	Content organization put aside, we have to figure a way to tie  
>>>> "make
>>>> man" in the doc-new dir with our make system in trunk/base, so that
>>>
>>> 1)
>>>> the regular "./configure && make && make install" dance (called
>>>> either when installing from source of while selfupdating) gets a  
>>>> set
>>>> of shiny new pages....
>>>
>>> 2)
>>>> or are you thinking of regen'ing them manually
>>>> in trunk/doc-new and copying them over to trunk/base/doc/ when you
>>>> think it's OK to "cut a release" for them?
>>>
>>> I would think option 1 would be best, unless there is a consensus
>>> otherwise.  I'm cc'ing doc team on this.  I'd prefer "live" docs  
>>> with head
>>> as now.  I haven't thought about what Makefile changes would be  
>>> necessary,
>>> and since the other doc team members are better programmers, I  
>>> probably
>>> wouldn't be the one to do it anyway.
>>
>> I also think 1) is the best way.
>>
>> But there is one problem: To make sure everybody gets the  
>> documentation when
>> checking out a copy from svn we either have to move the  
>> documentation in the
>> base/doc directory or use svn:externals so it gets downloaded.
>
> 	I originally thought 1) was the best approach too, but from what I  
> understand that would impose a dockbook requirement on all those  
> who simply want to build base for whatever purpose, and I seriously  
> dislike that idea.
[snip]
> I would very much prefer the second approach: that you guys "cut  
> releases" of our man pages and upload them to base/ when you feel  
> it's most appropriate; but...

I'll voice a mild preference for #1, sort of. That is, I think it's  
ok to require additional software installed for users of trunk. These  
users will likely already have a prior version of MacPorts installed  
and can simply "sudo port install docbook-xml" and then when they  
build MacPorts from trunk they get the very latest manpages  
automatically. That's good.

Users of downloaded versioned distribution archives, however (like a  
macports-1.6.0.tar.bz2 source archive), should not have to do that.  
Pre-generated manpages should be included with such source tarballs.


#2 seems problematic to me, and besides is against the Subversion  
tenet of not committing things to the repository that can be  
generated. Sometimes it's useful to do so, but in this case I don't  
think it's best. You run into problems of communicating to people  
that they should not commit to those generated files but rather to  
the original sources and then regenerate the files. Having one user  
lock the files is not great; perhaps we currently only have one user  
writing the documentation, but hopefully more will get involved at  
some point. And telling people to regenerate the manpages and commit  
them whenever they feel it's appropriate is no good, because either  
the person will say that every change is significant and worthwhile  
(why else would the change be made?) so after every change they have  
to regenerate the manpages and commit them, or the person says it's  
too complicated (or forgets) and never regenerates the manpages. In  
summary, I don't like it. :)