You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@couchdb.apache.org by Dirkjan Ochtman <di...@ochtman.nl> on 2013/05/20 14:58:55 UTC
Getting rid of file lists in documentation Makefiles
Hi there,
Keeping Makefile.am in sync with the actual documentation is a PITA,
and doesn't add any value. In fact, I broke the build over the weekend
by not removing some files from the Makefiles. Instead, we can use
invocations of find to find the relevant files in these cases:
html_files := $(shell find ./html/ -type f -not -wholename "*doctree*"
-not -name ".buildinfo")
image_files := $(shell find ../images/ -type f)
src_files := $(shell find ../src/ -name "*.rst" -or -name "conf.py")
src_files_html := $(shell find ../static/ ../templates/ -type f)
(This would replace the respective lists of files in
share/doc/build/Makefile.am.)
Anyone opposed to that?
Cheers,
Dirkjan
Re: Getting rid of file lists in documentation Makefiles
Posted by Dave Cottlehuber <dc...@jsonified.com>.
On 20 May 2013 22:55, Dirkjan Ochtman <di...@ochtman.nl> wrote:
> On Mon, May 20, 2013 at 5:39 PM, Noah Slater <ns...@apache.org> wrote:
>> I'm torn on this issue.
>>
>> See:
>>
>> http://www.gnu.org/software/automake/manual/automake.html#Wildcards
>>
>> (Please read that whole section.)
>>
>> Summary is:
>>
>> * Wildcards make it easy to distribute the wrong files (either too many, or
>> too few)
>>
>> * Wildcards are not portable
>
> Yes, I understand the concerns. On the other hand, I don't think most
> of those concerns apply cleanly to for example a Sphinx project. In
> particular, Sphinx already complains if src files are either missing
> or unused, so you'll get warnings about that. And Sphinx populates the
> build directory from scratch every time, so problems with the HTML
> output also seem fairly unlikely. On the other hand, forgetting to
> update the file lists in the Makefile.am will have no effect on
> building the docs, but will fail make distcheck. To me, at least, in
> this context, DRY a bigger concern to me.
>
> To be fair, portability is a concern. Dave, does the typical Windows
> build environment already have a find tool available to it? (Either
> just some compiled GNU tools or a full Cygwin environment?)
Today you need cygwin (or msys if you are courageous) to build couchdb, so yes.
>> Please also consider that with Benoit's rcouch merge, we're moving away from
>> Autotools entirely (I believe), so we will have the chance to throw off /
>> simplify a lot of this stuff.
I am very much hoping that post rebar (rcouch / bigcouch changes) it
will be possible to build on windows with just erlang, a c compiler,
and rebar. Oh and git, and those packaging tools. And that special
stuff for spidermonkey. And icu, and curl, and oh well. My idea is to
provide pre-compiled versions of those and make life easy for
everybody. Especially me.
A+
Dave
Re: Getting rid of file lists in documentation Makefiles
Posted by Jan Lehnardt <ja...@apache.org>.
On May 21, 2013, at 18:55 , Noah Slater <ns...@apache.org> wrote:
> Another way of looking at this is that by moving things to the docs, you're
> putting it behind a "commit bit" wall. That's appropriate in a some
> instances, but not in others.
>
> The wiki is open to developers, and good for collaboration, coordination,
> sharing resources, drafting things, etc. It's also used as a "noticeboard"
> in a few instances. This is why I think the wiki is better for project /
> community level stuff.
Another another way of looking at this is that we make it accessible to the
GitHub-on-website-fork-and-edit-and-pullrequest instead of the shoddy wiki
that everybody hates and nobody works on because the experience is so abysmal.
Jan
--
>
> It's not just Release_Procedure I'm concerned about. I did a quick survey
> of some of the top pages...
>
> ... But before I do the rundown, TL;DR: This seems complex. We might want
> to consider each wiki page separately.
>
> Quick rundown:
>
> http://wiki.apache.org/couchdb/Weekly_News
>
> - This is a WIP. I actually want to move to having an index here too, where
> each week's weekly news is drafted on the wiki. This would be a
> collaborative effort between developers and committers.
>
> http://wiki.apache.org/couchdb/SourceCode
>
> - This is in the "would be on the website if we had one" category.
>
> http://wiki.apache.org/couchdb/Release_Procedure
> http://wiki.apache.org/couchdb/Test_procedure
>
> - Both of these change quite frequently
>
> http://wiki.apache.org/couchdb/Release_Calendar
>
> - This makes no sense in the docs, because it's time-based statuses. It's
> more like a notice board.
>
> http://wiki.apache.org/couchdb/Committer_Election_Process
> http://wiki.apache.org/couchdb/PMC_Election_Process
> http://wiki.apache.org/couchdb/Community_Guide
>
> - Both WIPs. Will flesh these out over time. More of the "how we work" /
> process stuff. Expect there to be more of this over time. Having it on the
> wiki lets me do this WIP stuff without worrying about lots of messy stuff
> ending up in our manual.
>
> http://wiki.apache.org/couchdb/Roadmap_Process
> http://wiki.apache.org/couchdb/Merge_Procedure
>
> - More examples of docs that are not official, but are being *drafted* on
> the wiki. These would not be appropriate to include in the docs at this
> stage.
>
> http://wiki.apache.org/couchdb/CouchDB_in_the_wild
> http://wiki.apache.org/couchdb/People_on_the_Couch
> http://wiki.apache.org/couchdb/CouchDB_tools
>
> - This is more of the "noticeboard" type page. I see this as a way for the
> community to collaborate, communicate, etc. It wouldn't be appropriate to
> move this information to the manual or the developer handbook.
>
> http://wiki.apache.org/couchdb/CouchDB_meetups
>
> - Another one of the noticeboard type pages. This is time-based
> information, and is good on the wiki for collaboration. Would not be
> appropriate in the docs.
>
> http://wiki.apache.org/couchdb/Getting%20Help
>
> - Not sure about this. This is of the "would be on the website if we had
> one" category. If we put this in the docs, would it be obvious for people?
> How would you find it? Seems like a good case for being on the wiki?
>
> http://wiki.apache.org/couchdb/Frequently_asked_questions
> http://wiki.apache.org/couchdb/Breaking_changes
> http://wiki.apache.org/couchdb/Error_messages
> http://wiki.apache.org/couchdb/Troubleshooting
> http://wiki.apache.org/couchdb/Known_Problems
>
> - Good candidates for the docs.
>
> http://wiki.apache.org/couchdb/Development
>
> - Some good candidates here for the developer manual.
>
> http://wiki.apache.org/couchdb/Build_Process
>
> - This seems like a collaborative page. By which I mean, seems like the
> sort of thing to keep out of the docs. The wiki is sometimes used as just a
> scratch pad for people to share ideas in an informal way.
>
> http://wiki.apache.org/couchdb/Documentation
>
> - Another one that looks like a temporary collaboration page. Could
> probably do with an overhaul. After the update, this would probably be in
> the "would be on the website if we had one" category.
>
> http://wiki.apache.org/couchdb/ContributorWorkflow
>
> - Good candidate for the developer manual?
>
> http://wiki.apache.org/couchdb/Related_Projects
>
> - More of a noticeboard type page. Should be on the wiki for collaborative
> purposes.
>
>
>
>
> On 21 May 2013 17:23, Jan Lehnardt <ja...@apache.org> wrote:
>
>>
>> On May 21, 2013, at 17:25 , Noah Slater <ns...@apache.org> wrote:
>>
>>> I think the idea of a "Developer Handbook" is a good one.
>>> That's separate from a "CouchDB Manual" though.
>>
>> I’m roughly modelling this after the FreeBSD project which has
>>
>> http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/
>> (this corresponds to our “docs/”)
>>
>> and
>>
>> http://www.freebsd.org/doc/en_US.ISO8859-1/books/developers-handbook/
>>
>> (and a few more).
>>
>> So they have separate handbooks for this, and I think eventually that
>> makes sense for us as well, but I thought it was easiest to get started
>> with the developer handbook as a chapter/section in our docs/ until it
>> is substantial enough to make into its own.
>>
>>> For now, let's focus on getting the manual up to scratch, and let's keep
>>> the handbook stuff on the wiki.
>>>
>>> We can re-evaluate the situation later. I'm not married to it. :)
>>
>> I want to start this asap because we have some thing flying around
>> elsewhere that would benefit from getting into a definite location.
>>
>> Note though that Release_Procedure, while totally applicable to a
>> developer handbook, doesn’t have to migrate today if you prefer that.
>> If so, I’d suggest we just put a link into the developer handbook that
>> points to the wiki.
>>
>> Does that make sense?
>>
>> Jan
>> --
>>
>>
>>>
>>>
>>>
>>> On 21 May 2013 16:00, Jan Lehnardt <ja...@apache.org> wrote:
>>>
>>>>
>>>> On May 21, 2013, at 15:27 , Noah Slater <ns...@apache.org> wrote:
>>>>
>>>>> Actually, I prefer that project documentation be kept on the wiki.
>>>>>
>>>>> The docs that we have in the source are the "CouchDB Manual" (as I
>>>>> have titled it), and I see them as a reference work for CouchDB itself.
>>>>> Setting it up, configuring it, using it, etc.
>>>>>
>>>>> I see the wiki as more a place for the project / community to document
>>>> and
>>>>> organise itself. Consider that our homepage is a single HTML page. Most
>>>> of
>>>>> what we'd usually have on a website was moved to the wiki. So, I'm
>>>> talking
>>>>> release process, release calendar, source locations, active releases,
>>>>> committer election process, PMC election process, and soon, by-laws,
>>>>> community guides, etc.
>>>>>
>>>>> I'd like to keep this stuff on the wiki for now.
>>>>
>>>> I want to start a section in there that is called “The Developer
>> Handbook”.
>>>> The release docs would fit right in there, but this is your call
>>>> ultimately,
>>>> maybe we can have a pointer to the wiki from the docs/ then?
>>>>
>>>> Jan
>>>> --
>>>>
>>>>
>>>>
>>>>
>>>>>
>>>>>
>>>>> On 21 May 2013 13:20, Jan Lehnardt <ja...@apache.org> wrote:
>>>>>
>>>>>> On 21.05.2013, at 11:37, Dirkjan Ochtman <di...@ochtman.nl> wrote:
>>>>>>
>>>>>>> On Tue, May 21, 2013 at 11:33 AM, Jan Lehnardt <ja...@apache.org>
>> wrote:
>>>>>>>> It is all documented here:
>>>>>> http://wiki.apache.org/couchdb/Release_Procedure
>>>>>>>
>>>>>>> Oh, good. We should definitely pull stuff like that into a developer
>>>>>>> chapter of the docs, IMO.
>>>>>>
>>>>>> Go for it :)
>>>>>>
>>>>>> I think we have a rough consensus on moving most of the wiki into the
>>>>>> docs. Anyone, feel free to act on this!
>>>>>>
>>>>>> Jan
>>>>>> --
>>>>>>
>>>>>>
>>>>>
>>>>>
>>>>> --
>>>>> NS
>>>>
>>>>
>>>
>>>
>>> --
>>> NS
>>
>>
>
>
> --
> NS
Re: Getting rid of file lists in documentation Makefiles
Posted by Noah Slater <ns...@apache.org>.
Another way of looking at this is that by moving things to the docs, you're
putting it behind a "commit bit" wall. That's appropriate in a some
instances, but not in others.
The wiki is open to developers, and good for collaboration, coordination,
sharing resources, drafting things, etc. It's also used as a "noticeboard"
in a few instances. This is why I think the wiki is better for project /
community level stuff.
It's not just Release_Procedure I'm concerned about. I did a quick survey
of some of the top pages...
... But before I do the rundown, TL;DR: This seems complex. We might want
to consider each wiki page separately.
Quick rundown:
http://wiki.apache.org/couchdb/Weekly_News
- This is a WIP. I actually want to move to having an index here too, where
each week's weekly news is drafted on the wiki. This would be a
collaborative effort between developers and committers.
http://wiki.apache.org/couchdb/SourceCode
- This is in the "would be on the website if we had one" category.
http://wiki.apache.org/couchdb/Release_Procedure
http://wiki.apache.org/couchdb/Test_procedure
- Both of these change quite frequently
http://wiki.apache.org/couchdb/Release_Calendar
- This makes no sense in the docs, because it's time-based statuses. It's
more like a notice board.
http://wiki.apache.org/couchdb/Committer_Election_Process
http://wiki.apache.org/couchdb/PMC_Election_Process
http://wiki.apache.org/couchdb/Community_Guide
- Both WIPs. Will flesh these out over time. More of the "how we work" /
process stuff. Expect there to be more of this over time. Having it on the
wiki lets me do this WIP stuff without worrying about lots of messy stuff
ending up in our manual.
http://wiki.apache.org/couchdb/Roadmap_Process
http://wiki.apache.org/couchdb/Merge_Procedure
- More examples of docs that are not official, but are being *drafted* on
the wiki. These would not be appropriate to include in the docs at this
stage.
http://wiki.apache.org/couchdb/CouchDB_in_the_wild
http://wiki.apache.org/couchdb/People_on_the_Couch
http://wiki.apache.org/couchdb/CouchDB_tools
- This is more of the "noticeboard" type page. I see this as a way for the
community to collaborate, communicate, etc. It wouldn't be appropriate to
move this information to the manual or the developer handbook.
http://wiki.apache.org/couchdb/CouchDB_meetups
- Another one of the noticeboard type pages. This is time-based
information, and is good on the wiki for collaboration. Would not be
appropriate in the docs.
http://wiki.apache.org/couchdb/Getting%20Help
- Not sure about this. This is of the "would be on the website if we had
one" category. If we put this in the docs, would it be obvious for people?
How would you find it? Seems like a good case for being on the wiki?
http://wiki.apache.org/couchdb/Frequently_asked_questions
http://wiki.apache.org/couchdb/Breaking_changes
http://wiki.apache.org/couchdb/Error_messages
http://wiki.apache.org/couchdb/Troubleshooting
http://wiki.apache.org/couchdb/Known_Problems
- Good candidates for the docs.
http://wiki.apache.org/couchdb/Development
- Some good candidates here for the developer manual.
http://wiki.apache.org/couchdb/Build_Process
- This seems like a collaborative page. By which I mean, seems like the
sort of thing to keep out of the docs. The wiki is sometimes used as just a
scratch pad for people to share ideas in an informal way.
http://wiki.apache.org/couchdb/Documentation
- Another one that looks like a temporary collaboration page. Could
probably do with an overhaul. After the update, this would probably be in
the "would be on the website if we had one" category.
http://wiki.apache.org/couchdb/ContributorWorkflow
- Good candidate for the developer manual?
http://wiki.apache.org/couchdb/Related_Projects
- More of a noticeboard type page. Should be on the wiki for collaborative
purposes.
On 21 May 2013 17:23, Jan Lehnardt <ja...@apache.org> wrote:
>
> On May 21, 2013, at 17:25 , Noah Slater <ns...@apache.org> wrote:
>
> > I think the idea of a "Developer Handbook" is a good one.
> > That's separate from a "CouchDB Manual" though.
>
> I’m roughly modelling this after the FreeBSD project which has
>
> http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/
> (this corresponds to our “docs/”)
>
> and
>
> http://www.freebsd.org/doc/en_US.ISO8859-1/books/developers-handbook/
>
> (and a few more).
>
> So they have separate handbooks for this, and I think eventually that
> makes sense for us as well, but I thought it was easiest to get started
> with the developer handbook as a chapter/section in our docs/ until it
> is substantial enough to make into its own.
>
> > For now, let's focus on getting the manual up to scratch, and let's keep
> > the handbook stuff on the wiki.
> >
> > We can re-evaluate the situation later. I'm not married to it. :)
>
> I want to start this asap because we have some thing flying around
> elsewhere that would benefit from getting into a definite location.
>
> Note though that Release_Procedure, while totally applicable to a
> developer handbook, doesn’t have to migrate today if you prefer that.
> If so, I’d suggest we just put a link into the developer handbook that
> points to the wiki.
>
> Does that make sense?
>
> Jan
> --
>
>
> >
> >
> >
> > On 21 May 2013 16:00, Jan Lehnardt <ja...@apache.org> wrote:
> >
> >>
> >> On May 21, 2013, at 15:27 , Noah Slater <ns...@apache.org> wrote:
> >>
> >>> Actually, I prefer that project documentation be kept on the wiki.
> >>>
> >>> The docs that we have in the source are the "CouchDB Manual" (as I
> >>> have titled it), and I see them as a reference work for CouchDB itself.
> >>> Setting it up, configuring it, using it, etc.
> >>>
> >>> I see the wiki as more a place for the project / community to document
> >> and
> >>> organise itself. Consider that our homepage is a single HTML page. Most
> >> of
> >>> what we'd usually have on a website was moved to the wiki. So, I'm
> >> talking
> >>> release process, release calendar, source locations, active releases,
> >>> committer election process, PMC election process, and soon, by-laws,
> >>> community guides, etc.
> >>>
> >>> I'd like to keep this stuff on the wiki for now.
> >>
> >> I want to start a section in there that is called “The Developer
> Handbook”.
> >> The release docs would fit right in there, but this is your call
> >> ultimately,
> >> maybe we can have a pointer to the wiki from the docs/ then?
> >>
> >> Jan
> >> --
> >>
> >>
> >>
> >>
> >>>
> >>>
> >>> On 21 May 2013 13:20, Jan Lehnardt <ja...@apache.org> wrote:
> >>>
> >>>> On 21.05.2013, at 11:37, Dirkjan Ochtman <di...@ochtman.nl> wrote:
> >>>>
> >>>>> On Tue, May 21, 2013 at 11:33 AM, Jan Lehnardt <ja...@apache.org>
> wrote:
> >>>>>> It is all documented here:
> >>>> http://wiki.apache.org/couchdb/Release_Procedure
> >>>>>
> >>>>> Oh, good. We should definitely pull stuff like that into a developer
> >>>>> chapter of the docs, IMO.
> >>>>
> >>>> Go for it :)
> >>>>
> >>>> I think we have a rough consensus on moving most of the wiki into the
> >>>> docs. Anyone, feel free to act on this!
> >>>>
> >>>> Jan
> >>>> --
> >>>>
> >>>>
> >>>
> >>>
> >>> --
> >>> NS
> >>
> >>
> >
> >
> > --
> > NS
>
>
--
NS
Re: Getting rid of file lists in documentation Makefiles
Posted by Dirkjan Ochtman <di...@ochtman.nl>.
On Tue, May 21, 2013 at 9:33 PM, Noah Slater <ns...@apache.org> wrote:
>> This could easily go in a git branch of its own
>
> Repositories are cheep... ;)
Yeah, a branch doesn't make much sense to me.
Cheers,
Dirkjan
Re: Getting rid of file lists in documentation Makefiles
Posted by Noah Slater <ns...@apache.org>.
On 21 May 2013 20:19, Dave Cottlehuber <dc...@jsonified.com> wrote:
> This could easily go in a git branch of its own
>
Repositories are cheep... ;)
--
NS
Re: Getting rid of file lists in documentation Makefiles
Posted by Dave Cottlehuber <dc...@jsonified.com>.
On 21 May 2013 19:31, Noah Slater <ns...@apache.org> wrote:
> Always good when that happens.
+1 for migrating the bulk of the technical content to the rst docs,
nice list there Noah.
+1 for a developer manual, I need it too. This could easily go in a
git branch of its own and also be exposed on readthedocs or any other
website people prefer.
This sounds a little like the "move to confluence" thread from a
different perspective!
A+
Dave
Re: Getting rid of file lists in documentation Makefiles
Posted by Noah Slater <ns...@apache.org>.
Always good when that happens.
On 21 May 2013 18:19, Jan Lehnardt <ja...@apache.org> wrote:
> On May 21, 2013, at 19:17 , Noah Slater <ns...@apache.org> wrote:
>
> > As someone who contributes to the wiki quite frequently, I'm not sure I
> > agree about the experience being horrendous. However, I would like it to
> be
> > easier. But this is one of many considerations.
> >
> > As I say, we don't need to make any Big Decisions on this. Let's just
> take
> > things step-by-step.
> >
> > Some good candidates for the docs right away:
> >
> > http://wiki.apache.org/couchdb/Frequently_asked_questions
> > http://wiki.apache.org/couchdb/Breaking_changes
> > http://wiki.apache.org/couchdb/Error_messages
> > http://wiki.apache.org/couchdb/Troubleshooting
> > http://wiki.apache.org/couchdb/Known_Problems
> > http://wiki.apache.org/couchdb/ContributorWorkflow
> > http://wiki.apache.org/couchdb/Running%20CouchDB%20in%20Dev%20Mode
> > http://wiki.apache.org/couchdb/Source%20Code%20Repository%20Organization
> > http://wiki.apache.org/couchdb/Merge_Procedure
> > http://horicky.blogspot.ie/2008/10/couchdb-implementation.html
> >
> > And then lots of really obvious stuff like:
> >
> > http://wiki.apache.org/couchdb/Full_text_search
> > http://wiki.apache.org/couchdb/Adding_Runtime_Statistics
> > http://wiki.apache.org/couchdb/Tips_%26_Tricks_for_developers
> > http://wiki.apache.org/couchdb/couch_edocs
> >
> > ... And many more.
> >
> > There is plenty of work here for people to get stuck in to. And I'd like
> to
> > see us move this stuff over first.
> >
> > (I think because I am worried that we'll make a few new things in the
> docs,
> > forget to update them, and never bother to move the old stuff. I'd like
> to
> > see someone put in the legwork with the existing docs before we start
> > talking about new docs.)
> >
> > For the new stuff we've been talking about. Who we are, how we work, etc,
> > etc, let's just stick this on the wiki as part of a drafting process. In
> > fact, I would be completely happy with the general idea that the wiki is
> > the place where we draft things. And the doc is where we migrate things
> as
> > they mature.
>
> we are saying the same thing.
>
> Jan
> --
>
>
> >
> >
> >
> >
> > On 21 May 2013 18:08, Jan Lehnardt <ja...@apache.org> wrote:
> >
> >>
> >> On May 21, 2013, at 19:02 , Noah Slater <ns...@apache.org> wrote:
> >>
> >>> Also...
> >>>
> >>>
> >>> On 21 May 2013 17:23, Jan Lehnardt <ja...@apache.org> wrote:
> >>>
> >>>>
> >>>> On May 21, 2013, at 17:25 , Noah Slater <ns...@apache.org> wrote:
> >>>>
> >>>>> I think the idea of a "Developer Handbook" is a good one.
> >>>>> That's separate from a "CouchDB Manual" though.
> >>>>
> >>>> I’m roughly modelling this after the FreeBSD project which has
> >>>>
> >>>> http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/
> >>>> (this corresponds to our “docs/”)
> >>>>
> >>>> and
> >>>>
> >>>> http://www.freebsd.org/doc/en_US.ISO8859-1/books/developers-handbook/
> >>>>
> >>>> (and a few more).
> >>>>
> >>>> So they have separate handbooks for this, and I think eventually that
> >>>> makes sense for us as well, but I thought it was easiest to get
> started
> >>>> with the developer handbook as a chapter/section in our docs/ until it
> >>>> is substantial enough to make into its own.
> >>>
> >>>
> >>> It's worth considering that a developer handbook is "out-of-band" from
> a
> >>> release perspective.
> >>
> >> The 1.2.0 docs would explain the view engine as it existed then, the
> 1.3.0
> >> would explain the new view engine.
> >>
> >> Of course there is a lot of docs applicable to any version, but that is
> >> true for the HTTP API docs as well.
> >>
> >> Jan
> >> --
> >>
> >>
> >>
> >>> That is, developer information is bound to release
> >>> versions, so it makes no sense to freeze it at those points. But if
> >> you're
> >>> putting developer handbook information into the manual, then you are
> >> forced
> >>> to freeze it every time we do a release.
> >>>
> >>> For this reason, I am inclined to believe that any developer handbook
> is
> >>> kept out of the main Git repos.
> >>>
> >>>
> >>>>> For now, let's focus on getting the manual up to scratch, and let's
> >> keep
> >>>>> the handbook stuff on the wiki.
> >>>>>
> >>>>> We can re-evaluate the situation later. I'm not married to it. :)
> >>>>
> >>>> I want to start this asap because we have some thing flying around
> >>>> elsewhere that would benefit from getting into a definite location.
> >>>>
> >>>
> >>> Sure. But we already have a place for it: the wiki. This is the status
> >> quo.
> >>> :)
> >>>
> >>> Let's not bite off more than we can chew. The docs are very new, and
> >> we've
> >>> not even established a merge / release procedure for making sure they
> are
> >>> kept up to date.
> >>>
> >>> Once the docs are a little more settled, and the dev handbook stuff is
> a
> >>> little more mature, we can move the content wherever we like. Nothing
> has
> >>> to be permanent.
> >>>
> >>> --
> >>> NS
> >>
> >>
> >
> >
> > --
> > NS
>
>
--
NS
Re: Getting rid of file lists in documentation Makefiles
Posted by Jan Lehnardt <ja...@apache.org>.
On May 21, 2013, at 19:17 , Noah Slater <ns...@apache.org> wrote:
> As someone who contributes to the wiki quite frequently, I'm not sure I
> agree about the experience being horrendous. However, I would like it to be
> easier. But this is one of many considerations.
>
> As I say, we don't need to make any Big Decisions on this. Let's just take
> things step-by-step.
>
> Some good candidates for the docs right away:
>
> http://wiki.apache.org/couchdb/Frequently_asked_questions
> http://wiki.apache.org/couchdb/Breaking_changes
> http://wiki.apache.org/couchdb/Error_messages
> http://wiki.apache.org/couchdb/Troubleshooting
> http://wiki.apache.org/couchdb/Known_Problems
> http://wiki.apache.org/couchdb/ContributorWorkflow
> http://wiki.apache.org/couchdb/Running%20CouchDB%20in%20Dev%20Mode
> http://wiki.apache.org/couchdb/Source%20Code%20Repository%20Organization
> http://wiki.apache.org/couchdb/Merge_Procedure
> http://horicky.blogspot.ie/2008/10/couchdb-implementation.html
>
> And then lots of really obvious stuff like:
>
> http://wiki.apache.org/couchdb/Full_text_search
> http://wiki.apache.org/couchdb/Adding_Runtime_Statistics
> http://wiki.apache.org/couchdb/Tips_%26_Tricks_for_developers
> http://wiki.apache.org/couchdb/couch_edocs
>
> ... And many more.
>
> There is plenty of work here for people to get stuck in to. And I'd like to
> see us move this stuff over first.
>
> (I think because I am worried that we'll make a few new things in the docs,
> forget to update them, and never bother to move the old stuff. I'd like to
> see someone put in the legwork with the existing docs before we start
> talking about new docs.)
>
> For the new stuff we've been talking about. Who we are, how we work, etc,
> etc, let's just stick this on the wiki as part of a drafting process. In
> fact, I would be completely happy with the general idea that the wiki is
> the place where we draft things. And the doc is where we migrate things as
> they mature.
we are saying the same thing.
Jan
--
>
>
>
>
> On 21 May 2013 18:08, Jan Lehnardt <ja...@apache.org> wrote:
>
>>
>> On May 21, 2013, at 19:02 , Noah Slater <ns...@apache.org> wrote:
>>
>>> Also...
>>>
>>>
>>> On 21 May 2013 17:23, Jan Lehnardt <ja...@apache.org> wrote:
>>>
>>>>
>>>> On May 21, 2013, at 17:25 , Noah Slater <ns...@apache.org> wrote:
>>>>
>>>>> I think the idea of a "Developer Handbook" is a good one.
>>>>> That's separate from a "CouchDB Manual" though.
>>>>
>>>> I’m roughly modelling this after the FreeBSD project which has
>>>>
>>>> http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/
>>>> (this corresponds to our “docs/”)
>>>>
>>>> and
>>>>
>>>> http://www.freebsd.org/doc/en_US.ISO8859-1/books/developers-handbook/
>>>>
>>>> (and a few more).
>>>>
>>>> So they have separate handbooks for this, and I think eventually that
>>>> makes sense for us as well, but I thought it was easiest to get started
>>>> with the developer handbook as a chapter/section in our docs/ until it
>>>> is substantial enough to make into its own.
>>>
>>>
>>> It's worth considering that a developer handbook is "out-of-band" from a
>>> release perspective.
>>
>> The 1.2.0 docs would explain the view engine as it existed then, the 1.3.0
>> would explain the new view engine.
>>
>> Of course there is a lot of docs applicable to any version, but that is
>> true for the HTTP API docs as well.
>>
>> Jan
>> --
>>
>>
>>
>>> That is, developer information is bound to release
>>> versions, so it makes no sense to freeze it at those points. But if
>> you're
>>> putting developer handbook information into the manual, then you are
>> forced
>>> to freeze it every time we do a release.
>>>
>>> For this reason, I am inclined to believe that any developer handbook is
>>> kept out of the main Git repos.
>>>
>>>
>>>>> For now, let's focus on getting the manual up to scratch, and let's
>> keep
>>>>> the handbook stuff on the wiki.
>>>>>
>>>>> We can re-evaluate the situation later. I'm not married to it. :)
>>>>
>>>> I want to start this asap because we have some thing flying around
>>>> elsewhere that would benefit from getting into a definite location.
>>>>
>>>
>>> Sure. But we already have a place for it: the wiki. This is the status
>> quo.
>>> :)
>>>
>>> Let's not bite off more than we can chew. The docs are very new, and
>> we've
>>> not even established a merge / release procedure for making sure they are
>>> kept up to date.
>>>
>>> Once the docs are a little more settled, and the dev handbook stuff is a
>>> little more mature, we can move the content wherever we like. Nothing has
>>> to be permanent.
>>>
>>> --
>>> NS
>>
>>
>
>
> --
> NS
Re: Getting rid of file lists in documentation Makefiles
Posted by Noah Slater <ns...@apache.org>.
As someone who contributes to the wiki quite frequently, I'm not sure I
agree about the experience being horrendous. However, I would like it to be
easier. But this is one of many considerations.
As I say, we don't need to make any Big Decisions on this. Let's just take
things step-by-step.
Some good candidates for the docs right away:
http://wiki.apache.org/couchdb/Frequently_asked_questions
http://wiki.apache.org/couchdb/Breaking_changes
http://wiki.apache.org/couchdb/Error_messages
http://wiki.apache.org/couchdb/Troubleshooting
http://wiki.apache.org/couchdb/Known_Problems
http://wiki.apache.org/couchdb/ContributorWorkflow
http://wiki.apache.org/couchdb/Running%20CouchDB%20in%20Dev%20Mode
http://wiki.apache.org/couchdb/Source%20Code%20Repository%20Organization
http://wiki.apache.org/couchdb/Merge_Procedure
http://horicky.blogspot.ie/2008/10/couchdb-implementation.html
And then lots of really obvious stuff like:
http://wiki.apache.org/couchdb/Full_text_search
http://wiki.apache.org/couchdb/Adding_Runtime_Statistics
http://wiki.apache.org/couchdb/Tips_%26_Tricks_for_developers
http://wiki.apache.org/couchdb/couch_edocs
... And many more.
There is plenty of work here for people to get stuck in to. And I'd like to
see us move this stuff over first.
(I think because I am worried that we'll make a few new things in the docs,
forget to update them, and never bother to move the old stuff. I'd like to
see someone put in the legwork with the existing docs before we start
talking about new docs.)
For the new stuff we've been talking about. Who we are, how we work, etc,
etc, let's just stick this on the wiki as part of a drafting process. In
fact, I would be completely happy with the general idea that the wiki is
the place where we draft things. And the doc is where we migrate things as
they mature.
On 21 May 2013 18:08, Jan Lehnardt <ja...@apache.org> wrote:
>
> On May 21, 2013, at 19:02 , Noah Slater <ns...@apache.org> wrote:
>
> > Also...
> >
> >
> > On 21 May 2013 17:23, Jan Lehnardt <ja...@apache.org> wrote:
> >
> >>
> >> On May 21, 2013, at 17:25 , Noah Slater <ns...@apache.org> wrote:
> >>
> >>> I think the idea of a "Developer Handbook" is a good one.
> >>> That's separate from a "CouchDB Manual" though.
> >>
> >> I’m roughly modelling this after the FreeBSD project which has
> >>
> >> http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/
> >> (this corresponds to our “docs/”)
> >>
> >> and
> >>
> >> http://www.freebsd.org/doc/en_US.ISO8859-1/books/developers-handbook/
> >>
> >> (and a few more).
> >>
> >> So they have separate handbooks for this, and I think eventually that
> >> makes sense for us as well, but I thought it was easiest to get started
> >> with the developer handbook as a chapter/section in our docs/ until it
> >> is substantial enough to make into its own.
> >
> >
> > It's worth considering that a developer handbook is "out-of-band" from a
> > release perspective.
>
> The 1.2.0 docs would explain the view engine as it existed then, the 1.3.0
> would explain the new view engine.
>
> Of course there is a lot of docs applicable to any version, but that is
> true for the HTTP API docs as well.
>
> Jan
> --
>
>
>
> > That is, developer information is bound to release
> > versions, so it makes no sense to freeze it at those points. But if
> you're
> > putting developer handbook information into the manual, then you are
> forced
> > to freeze it every time we do a release.
> >
> > For this reason, I am inclined to believe that any developer handbook is
> > kept out of the main Git repos.
> >
> >
> >>> For now, let's focus on getting the manual up to scratch, and let's
> keep
> >>> the handbook stuff on the wiki.
> >>>
> >>> We can re-evaluate the situation later. I'm not married to it. :)
> >>
> >> I want to start this asap because we have some thing flying around
> >> elsewhere that would benefit from getting into a definite location.
> >>
> >
> > Sure. But we already have a place for it: the wiki. This is the status
> quo.
> > :)
> >
> > Let's not bite off more than we can chew. The docs are very new, and
> we've
> > not even established a merge / release procedure for making sure they are
> > kept up to date.
> >
> > Once the docs are a little more settled, and the dev handbook stuff is a
> > little more mature, we can move the content wherever we like. Nothing has
> > to be permanent.
> >
> > --
> > NS
>
>
--
NS
Re: Getting rid of file lists in documentation Makefiles
Posted by Jan Lehnardt <ja...@apache.org>.
On May 21, 2013, at 19:02 , Noah Slater <ns...@apache.org> wrote:
> Also...
>
>
> On 21 May 2013 17:23, Jan Lehnardt <ja...@apache.org> wrote:
>
>>
>> On May 21, 2013, at 17:25 , Noah Slater <ns...@apache.org> wrote:
>>
>>> I think the idea of a "Developer Handbook" is a good one.
>>> That's separate from a "CouchDB Manual" though.
>>
>> I’m roughly modelling this after the FreeBSD project which has
>>
>> http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/
>> (this corresponds to our “docs/”)
>>
>> and
>>
>> http://www.freebsd.org/doc/en_US.ISO8859-1/books/developers-handbook/
>>
>> (and a few more).
>>
>> So they have separate handbooks for this, and I think eventually that
>> makes sense for us as well, but I thought it was easiest to get started
>> with the developer handbook as a chapter/section in our docs/ until it
>> is substantial enough to make into its own.
>
>
> It's worth considering that a developer handbook is "out-of-band" from a
> release perspective.
The 1.2.0 docs would explain the view engine as it existed then, the 1.3.0
would explain the new view engine.
Of course there is a lot of docs applicable to any version, but that is
true for the HTTP API docs as well.
Jan
--
> That is, developer information is bound to release
> versions, so it makes no sense to freeze it at those points. But if you're
> putting developer handbook information into the manual, then you are forced
> to freeze it every time we do a release.
>
> For this reason, I am inclined to believe that any developer handbook is
> kept out of the main Git repos.
>
>
>>> For now, let's focus on getting the manual up to scratch, and let's keep
>>> the handbook stuff on the wiki.
>>>
>>> We can re-evaluate the situation later. I'm not married to it. :)
>>
>> I want to start this asap because we have some thing flying around
>> elsewhere that would benefit from getting into a definite location.
>>
>
> Sure. But we already have a place for it: the wiki. This is the status quo.
> :)
>
> Let's not bite off more than we can chew. The docs are very new, and we've
> not even established a merge / release procedure for making sure they are
> kept up to date.
>
> Once the docs are a little more settled, and the dev handbook stuff is a
> little more mature, we can move the content wherever we like. Nothing has
> to be permanent.
>
> --
> NS
Re: Getting rid of file lists in documentation Makefiles
Posted by Noah Slater <ns...@apache.org>.
* developer information is _not_ bound to release versions
P.S. I think this is actually quite an important point. Maybe even the most
important point.
On 21 May 2013 18:02, Noah Slater <ns...@apache.org> wrote:
> Also...
>
>
> On 21 May 2013 17:23, Jan Lehnardt <ja...@apache.org> wrote:
>
>>
>> On May 21, 2013, at 17:25 , Noah Slater <ns...@apache.org> wrote:
>>
>> > I think the idea of a "Developer Handbook" is a good one.
>> > That's separate from a "CouchDB Manual" though.
>>
>> I’m roughly modelling this after the FreeBSD project which has
>>
>> http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/
>> (this corresponds to our “docs/”)
>>
>> and
>>
>> http://www.freebsd.org/doc/en_US.ISO8859-1/books/developers-handbook/
>>
>> (and a few more).
>>
>> So they have separate handbooks for this, and I think eventually that
>> makes sense for us as well, but I thought it was easiest to get started
>> with the developer handbook as a chapter/section in our docs/ until it
>> is substantial enough to make into its own.
>
>
> It's worth considering that a developer handbook is "out-of-band" from a
> release perspective. That is, developer information is bound to release
> versions, so it makes no sense to freeze it at those points. But if you're
> putting developer handbook information into the manual, then you are forced
> to freeze it every time we do a release.
>
> For this reason, I am inclined to believe that any developer handbook is
> kept out of the main Git repos.
>
>
>> > For now, let's focus on getting the manual up to scratch, and let's
>> keep
>> > the handbook stuff on the wiki.
>> >
>> > We can re-evaluate the situation later. I'm not married to it. :)
>>
>> I want to start this asap because we have some thing flying around
>> elsewhere that would benefit from getting into a definite location.
>>
>
> Sure. But we already have a place for it: the wiki. This is the status
> quo. :)
>
> Let's not bite off more than we can chew. The docs are very new, and we've
> not even established a merge / release procedure for making sure they are
> kept up to date.
>
> Once the docs are a little more settled, and the dev handbook stuff is a
> little more mature, we can move the content wherever we like. Nothing has
> to be permanent.
>
> --
> NS
>
--
NS
Re: Getting rid of file lists in documentation Makefiles
Posted by Noah Slater <ns...@apache.org>.
Also...
On 21 May 2013 17:23, Jan Lehnardt <ja...@apache.org> wrote:
>
> On May 21, 2013, at 17:25 , Noah Slater <ns...@apache.org> wrote:
>
> > I think the idea of a "Developer Handbook" is a good one.
> > That's separate from a "CouchDB Manual" though.
>
> I’m roughly modelling this after the FreeBSD project which has
>
> http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/
> (this corresponds to our “docs/”)
>
> and
>
> http://www.freebsd.org/doc/en_US.ISO8859-1/books/developers-handbook/
>
> (and a few more).
>
> So they have separate handbooks for this, and I think eventually that
> makes sense for us as well, but I thought it was easiest to get started
> with the developer handbook as a chapter/section in our docs/ until it
> is substantial enough to make into its own.
It's worth considering that a developer handbook is "out-of-band" from a
release perspective. That is, developer information is bound to release
versions, so it makes no sense to freeze it at those points. But if you're
putting developer handbook information into the manual, then you are forced
to freeze it every time we do a release.
For this reason, I am inclined to believe that any developer handbook is
kept out of the main Git repos.
> > For now, let's focus on getting the manual up to scratch, and let's keep
> > the handbook stuff on the wiki.
> >
> > We can re-evaluate the situation later. I'm not married to it. :)
>
> I want to start this asap because we have some thing flying around
> elsewhere that would benefit from getting into a definite location.
>
Sure. But we already have a place for it: the wiki. This is the status quo.
:)
Let's not bite off more than we can chew. The docs are very new, and we've
not even established a merge / release procedure for making sure they are
kept up to date.
Once the docs are a little more settled, and the dev handbook stuff is a
little more mature, we can move the content wherever we like. Nothing has
to be permanent.
--
NS
Re: Getting rid of file lists in documentation Makefiles
Posted by Jan Lehnardt <ja...@apache.org>.
On May 21, 2013, at 17:25 , Noah Slater <ns...@apache.org> wrote:
> I think the idea of a "Developer Handbook" is a good one.
> That's separate from a "CouchDB Manual" though.
I’m roughly modelling this after the FreeBSD project which has
http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/
(this corresponds to our “docs/”)
and
http://www.freebsd.org/doc/en_US.ISO8859-1/books/developers-handbook/
(and a few more).
So they have separate handbooks for this, and I think eventually that
makes sense for us as well, but I thought it was easiest to get started
with the developer handbook as a chapter/section in our docs/ until it
is substantial enough to make into its own.
> For now, let's focus on getting the manual up to scratch, and let's keep
> the handbook stuff on the wiki.
>
> We can re-evaluate the situation later. I'm not married to it. :)
I want to start this asap because we have some thing flying around
elsewhere that would benefit from getting into a definite location.
Note though that Release_Procedure, while totally applicable to a
developer handbook, doesn’t have to migrate today if you prefer that.
If so, I’d suggest we just put a link into the developer handbook that
points to the wiki.
Does that make sense?
Jan
--
>
>
>
> On 21 May 2013 16:00, Jan Lehnardt <ja...@apache.org> wrote:
>
>>
>> On May 21, 2013, at 15:27 , Noah Slater <ns...@apache.org> wrote:
>>
>>> Actually, I prefer that project documentation be kept on the wiki.
>>>
>>> The docs that we have in the source are the "CouchDB Manual" (as I
>>> have titled it), and I see them as a reference work for CouchDB itself.
>>> Setting it up, configuring it, using it, etc.
>>>
>>> I see the wiki as more a place for the project / community to document
>> and
>>> organise itself. Consider that our homepage is a single HTML page. Most
>> of
>>> what we'd usually have on a website was moved to the wiki. So, I'm
>> talking
>>> release process, release calendar, source locations, active releases,
>>> committer election process, PMC election process, and soon, by-laws,
>>> community guides, etc.
>>>
>>> I'd like to keep this stuff on the wiki for now.
>>
>> I want to start a section in there that is called “The Developer Handbook”.
>> The release docs would fit right in there, but this is your call
>> ultimately,
>> maybe we can have a pointer to the wiki from the docs/ then?
>>
>> Jan
>> --
>>
>>
>>
>>
>>>
>>>
>>> On 21 May 2013 13:20, Jan Lehnardt <ja...@apache.org> wrote:
>>>
>>>> On 21.05.2013, at 11:37, Dirkjan Ochtman <di...@ochtman.nl> wrote:
>>>>
>>>>> On Tue, May 21, 2013 at 11:33 AM, Jan Lehnardt <ja...@apache.org> wrote:
>>>>>> It is all documented here:
>>>> http://wiki.apache.org/couchdb/Release_Procedure
>>>>>
>>>>> Oh, good. We should definitely pull stuff like that into a developer
>>>>> chapter of the docs, IMO.
>>>>
>>>> Go for it :)
>>>>
>>>> I think we have a rough consensus on moving most of the wiki into the
>>>> docs. Anyone, feel free to act on this!
>>>>
>>>> Jan
>>>> --
>>>>
>>>>
>>>
>>>
>>> --
>>> NS
>>
>>
>
>
> --
> NS
Re: Getting rid of file lists in documentation Makefiles
Posted by Noah Slater <ns...@apache.org>.
I think the idea of a "Developer Handbook" is a good one.
That's separate from a "CouchDB Manual" though.
For now, let's focus on getting the manual up to scratch, and let's keep
the handbook stuff on the wiki.
We can re-evaluate the situation later. I'm not married to it. :)
On 21 May 2013 16:00, Jan Lehnardt <ja...@apache.org> wrote:
>
> On May 21, 2013, at 15:27 , Noah Slater <ns...@apache.org> wrote:
>
> > Actually, I prefer that project documentation be kept on the wiki.
> >
> > The docs that we have in the source are the "CouchDB Manual" (as I
> > have titled it), and I see them as a reference work for CouchDB itself.
> > Setting it up, configuring it, using it, etc.
> >
> > I see the wiki as more a place for the project / community to document
> and
> > organise itself. Consider that our homepage is a single HTML page. Most
> of
> > what we'd usually have on a website was moved to the wiki. So, I'm
> talking
> > release process, release calendar, source locations, active releases,
> > committer election process, PMC election process, and soon, by-laws,
> > community guides, etc.
> >
> > I'd like to keep this stuff on the wiki for now.
>
> I want to start a section in there that is called “The Developer Handbook”.
> The release docs would fit right in there, but this is your call
> ultimately,
> maybe we can have a pointer to the wiki from the docs/ then?
>
> Jan
> --
>
>
>
>
> >
> >
> > On 21 May 2013 13:20, Jan Lehnardt <ja...@apache.org> wrote:
> >
> >> On 21.05.2013, at 11:37, Dirkjan Ochtman <di...@ochtman.nl> wrote:
> >>
> >>> On Tue, May 21, 2013 at 11:33 AM, Jan Lehnardt <ja...@apache.org> wrote:
> >>>> It is all documented here:
> >> http://wiki.apache.org/couchdb/Release_Procedure
> >>>
> >>> Oh, good. We should definitely pull stuff like that into a developer
> >>> chapter of the docs, IMO.
> >>
> >> Go for it :)
> >>
> >> I think we have a rough consensus on moving most of the wiki into the
> >> docs. Anyone, feel free to act on this!
> >>
> >> Jan
> >> --
> >>
> >>
> >
> >
> > --
> > NS
>
>
--
NS
Re: Getting rid of file lists in documentation Makefiles
Posted by Filippo Fadda <fi...@programmazione.it>.
On May 21, 2013, at 5:00 PM, Jan Lehnardt wrote:
> I want to start a section in there that is called “The Developer Handbook”.
+1
-Filippo
Re: Getting rid of file lists in documentation Makefiles
Posted by Jan Lehnardt <ja...@apache.org>.
On May 21, 2013, at 15:27 , Noah Slater <ns...@apache.org> wrote:
> Actually, I prefer that project documentation be kept on the wiki.
>
> The docs that we have in the source are the "CouchDB Manual" (as I
> have titled it), and I see them as a reference work for CouchDB itself.
> Setting it up, configuring it, using it, etc.
>
> I see the wiki as more a place for the project / community to document and
> organise itself. Consider that our homepage is a single HTML page. Most of
> what we'd usually have on a website was moved to the wiki. So, I'm talking
> release process, release calendar, source locations, active releases,
> committer election process, PMC election process, and soon, by-laws,
> community guides, etc.
>
> I'd like to keep this stuff on the wiki for now.
I want to start a section in there that is called “The Developer Handbook”.
The release docs would fit right in there, but this is your call ultimately,
maybe we can have a pointer to the wiki from the docs/ then?
Jan
--
>
>
> On 21 May 2013 13:20, Jan Lehnardt <ja...@apache.org> wrote:
>
>> On 21.05.2013, at 11:37, Dirkjan Ochtman <di...@ochtman.nl> wrote:
>>
>>> On Tue, May 21, 2013 at 11:33 AM, Jan Lehnardt <ja...@apache.org> wrote:
>>>> It is all documented here:
>> http://wiki.apache.org/couchdb/Release_Procedure
>>>
>>> Oh, good. We should definitely pull stuff like that into a developer
>>> chapter of the docs, IMO.
>>
>> Go for it :)
>>
>> I think we have a rough consensus on moving most of the wiki into the
>> docs. Anyone, feel free to act on this!
>>
>> Jan
>> --
>>
>>
>
>
> --
> NS
Re: Getting rid of file lists in documentation Makefiles
Posted by Noah Slater <ns...@apache.org>.
Actually, I prefer that project documentation be kept on the wiki.
The docs that we have in the source are the "CouchDB Manual" (as I
have titled it), and I see them as a reference work for CouchDB itself.
Setting it up, configuring it, using it, etc.
I see the wiki as more a place for the project / community to document and
organise itself. Consider that our homepage is a single HTML page. Most of
what we'd usually have on a website was moved to the wiki. So, I'm talking
release process, release calendar, source locations, active releases,
committer election process, PMC election process, and soon, by-laws,
community guides, etc.
I'd like to keep this stuff on the wiki for now.
On 21 May 2013 13:20, Jan Lehnardt <ja...@apache.org> wrote:
> On 21.05.2013, at 11:37, Dirkjan Ochtman <di...@ochtman.nl> wrote:
>
> > On Tue, May 21, 2013 at 11:33 AM, Jan Lehnardt <ja...@apache.org> wrote:
> >> It is all documented here:
> http://wiki.apache.org/couchdb/Release_Procedure
> >
> > Oh, good. We should definitely pull stuff like that into a developer
> > chapter of the docs, IMO.
>
> Go for it :)
>
> I think we have a rough consensus on moving most of the wiki into the
> docs. Anyone, feel free to act on this!
>
> Jan
> --
>
>
--
NS
Re: Getting rid of file lists in documentation Makefiles
Posted by Jan Lehnardt <ja...@apache.org>.
On 21.05.2013, at 11:37, Dirkjan Ochtman <di...@ochtman.nl> wrote:
> On Tue, May 21, 2013 at 11:33 AM, Jan Lehnardt <ja...@apache.org> wrote:
>> It is all documented here: http://wiki.apache.org/couchdb/Release_Procedure
>
> Oh, good. We should definitely pull stuff like that into a developer
> chapter of the docs, IMO.
Go for it :)
I think we have a rough consensus on moving most of the wiki into the docs. Anyone, feel free to act on this!
Jan
--
Re: Getting rid of file lists in documentation Makefiles
Posted by Benoit Chesneau <bc...@gmail.com>.
+1
On Tuesday, May 21, 2013, Dirkjan Ochtman wrote:
> On Tue, May 21, 2013 at 11:33 AM, Jan Lehnardt <jan@apache.org<javascript:;>>
> wrote:
> > It is all documented here:
> http://wiki.apache.org/couchdb/Release_Procedure
>
> Oh, good. We should definitely pull stuff like that into a developer
> chapter of the docs, IMO.
>
> Cheers,
>
> Dirkjan
>
Re: Getting rid of file lists in documentation Makefiles
Posted by Dirkjan Ochtman <di...@ochtman.nl>.
On Tue, May 21, 2013 at 11:33 AM, Jan Lehnardt <ja...@apache.org> wrote:
> It is all documented here: http://wiki.apache.org/couchdb/Release_Procedure
Oh, good. We should definitely pull stuff like that into a developer
chapter of the docs, IMO.
Cheers,
Dirkjan
Re: Getting rid of file lists in documentation Makefiles
Posted by Jan Lehnardt <ja...@apache.org>.
On May 21, 2013, at 09:33 , Dirkjan Ochtman <di...@ochtman.nl> wrote:
> On Mon, May 20, 2013 at 11:29 PM, Noah Slater <ns...@apache.org> wrote:
>> My concern is that when you use wildcards, a malicious (or broken) program
>> could add files to the output that are then bundled up, and we end up
>> shipping them in a release. At the moment, every file that we ship has been
>> explcitly included. Having said that, my release procedure is now
>> sufficiently advanced that I can detect missing/extra files, as well as
>> "surprising" content. So I am not sure I need to be as vigilant about this
>> as I used to be...
>
> Your release procedure being advanced sounds like bus factor danger;
> is all of that in the admin-repo, or available somewhere else?
It is all documented here: http://wiki.apache.org/couchdb/Release_Procedure
> I could
> see myself doing some release management to lighten some of your load.
Woohoo! :)
Jan
--
>
>> With that in mind, I'd say: do whatever you think is best.
>
> I'll wait a bit for Benoit's build system refactor to land.
>
> Cheers,
>
> Dirkjan
Re: Getting rid of file lists in documentation Makefiles
Posted by Dirkjan Ochtman <di...@ochtman.nl>.
On Mon, May 20, 2013 at 11:29 PM, Noah Slater <ns...@apache.org> wrote:
> My concern is that when you use wildcards, a malicious (or broken) program
> could add files to the output that are then bundled up, and we end up
> shipping them in a release. At the moment, every file that we ship has been
> explcitly included. Having said that, my release procedure is now
> sufficiently advanced that I can detect missing/extra files, as well as
> "surprising" content. So I am not sure I need to be as vigilant about this
> as I used to be...
Your release procedure being advanced sounds like bus factor danger;
is all of that in the admin-repo, or available somewhere else? I could
see myself doing some release management to lighten some of your load.
> With that in mind, I'd say: do whatever you think is best.
I'll wait a bit for Benoit's build system refactor to land.
Cheers,
Dirkjan
Re: Getting rid of file lists in documentation Makefiles
Posted by Noah Slater <ns...@apache.org>.
My concern is that when you use wildcards, a malicious (or broken) program
could add files to the output that are then bundled up, and we end up
shipping them in a release. At the moment, every file that we ship has been
explcitly included. Having said that, my release procedure is now
sufficiently advanced that I can detect missing/extra files, as well as
"surprising" content. So I am not sure I need to be as vigilant about this
as I used to be...
With that in mind, I'd say: do whatever you think is best.
On 20 May 2013 21:55, Dirkjan Ochtman <di...@ochtman.nl> wrote:
> On Mon, May 20, 2013 at 5:39 PM, Noah Slater <ns...@apache.org> wrote:
> > I'm torn on this issue.
> >
> > See:
> >
> > http://www.gnu.org/software/automake/manual/automake.html#Wildcards
> >
> > (Please read that whole section.)
> >
> > Summary is:
> >
> > * Wildcards make it easy to distribute the wrong files (either too
> many, or
> > too few)
> >
> > * Wildcards are not portable
>
> Yes, I understand the concerns. On the other hand, I don't think most
> of those concerns apply cleanly to for example a Sphinx project. In
> particular, Sphinx already complains if src files are either missing
> or unused, so you'll get warnings about that. And Sphinx populates the
> build directory from scratch every time, so problems with the HTML
> output also seem fairly unlikely. On the other hand, forgetting to
> update the file lists in the Makefile.am will have no effect on
> building the docs, but will fail make distcheck. To me, at least, in
> this context, DRY a bigger concern to me.
>
> To be fair, portability is a concern. Dave, does the typical Windows
> build environment already have a find tool available to it? (Either
> just some compiled GNU tools or a full Cygwin environment?)
>
> > Please also consider that with Benoit's rcouch merge, we're moving away
> from
> > Autotools entirely (I believe), so we will have the chance to throw off /
> > simplify a lot of this stuff.
>
> Ah, yes. Do we have a time frame for that?
>
> > What are your thoughts having read that section?
>
> Still the same, in this particular context, for the reasons explained
> above.
>
> Cheers,
>
> Dirkjan
>
--
NS
Re: Getting rid of file lists in documentation Makefiles
Posted by Benoit Chesneau <bc...@gmail.com>.
On May 20, 2013 10:56 PM, "Dirkjan Ochtman" <di...@ochtman.nl> wrote:
>
> On Mon, May 20, 2013 at 5:39 PM, Noah Slater <ns...@apache.org> wrote:
> > I'm torn on this issue.
> >
> > See:
> >
> > http://www.gnu.org/software/automake/manual/automake.html#Wildcards
> >
> > (Please read that whole section.)
> >
> > Summary is:
> >
> > * Wildcards make it easy to distribute the wrong files (either too
many, or
> > too few)
> >
> > * Wildcards are not portable
>
> Yes, I understand the concerns. On the other hand, I don't think most
> of those concerns apply cleanly to for example a Sphinx project. In
> particular, Sphinx already complains if src files are either missing
> or unused, so you'll get warnings about that. And Sphinx populates the
> build directory from scratch every time, so problems with the HTML
> output also seem fairly unlikely. On the other hand, forgetting to
> update the file lists in the Makefile.am will have no effect on
> building the docs, but will fail make distcheck. To me, at least, in
> this context, DRY a bigger concern to me.
>
> To be fair, portability is a concern. Dave, does the typical Windows
> build environment already have a find tool available to it? (Either
> just some compiled GNU tools or a full Cygwin environment?)
>
> > Please also consider that with Benoit's rcouch merge, we're moving away
from
> > Autotools entirely (I believe), so we will have the chance to throw off
/
> > simplify a lot of this stuff.
>
> Ah, yes. Do we have a time frame for that?
sometime this month but before the next.
- benoit
>
> > What are your thoughts having read that section?
>
> Still the same, in this particular context, for the reasons explained
above.
>
> Cheers,
>
> Dirkjan
Re: Getting rid of file lists in documentation Makefiles
Posted by Dirkjan Ochtman <di...@ochtman.nl>.
On Mon, May 20, 2013 at 5:39 PM, Noah Slater <ns...@apache.org> wrote:
> I'm torn on this issue.
>
> See:
>
> http://www.gnu.org/software/automake/manual/automake.html#Wildcards
>
> (Please read that whole section.)
>
> Summary is:
>
> * Wildcards make it easy to distribute the wrong files (either too many, or
> too few)
>
> * Wildcards are not portable
Yes, I understand the concerns. On the other hand, I don't think most
of those concerns apply cleanly to for example a Sphinx project. In
particular, Sphinx already complains if src files are either missing
or unused, so you'll get warnings about that. And Sphinx populates the
build directory from scratch every time, so problems with the HTML
output also seem fairly unlikely. On the other hand, forgetting to
update the file lists in the Makefile.am will have no effect on
building the docs, but will fail make distcheck. To me, at least, in
this context, DRY a bigger concern to me.
To be fair, portability is a concern. Dave, does the typical Windows
build environment already have a find tool available to it? (Either
just some compiled GNU tools or a full Cygwin environment?)
> Please also consider that with Benoit's rcouch merge, we're moving away from
> Autotools entirely (I believe), so we will have the chance to throw off /
> simplify a lot of this stuff.
Ah, yes. Do we have a time frame for that?
> What are your thoughts having read that section?
Still the same, in this particular context, for the reasons explained above.
Cheers,
Dirkjan
Re: Getting rid of file lists in documentation Makefiles
Posted by Noah Slater <ns...@apache.org>.
I'm torn on this issue.
See:
http://www.gnu.org/software/automake/manual/automake.html#Wildcards
(Please read that whole section.)
Summary is:
* Wildcards make it easy to distribute the wrong files (either too many,
or too few)
* Wildcards are not portable
Please also consider that with Benoit's rcouch merge, we're moving away
from Autotools entirely (I believe), so we will have the chance to throw
off / simplify a lot of this stuff.
What are your thoughts having read that section?
On 20 May 2013 13:58, Dirkjan Ochtman <di...@ochtman.nl> wrote:
> Hi there,
>
> Keeping Makefile.am in sync with the actual documentation is a PITA,
> and doesn't add any value. In fact, I broke the build over the weekend
> by not removing some files from the Makefiles. Instead, we can use
> invocations of find to find the relevant files in these cases:
>
> html_files := $(shell find ./html/ -type f -not -wholename "*doctree*"
> -not -name ".buildinfo")
> image_files := $(shell find ../images/ -type f)
> src_files := $(shell find ../src/ -name "*.rst" -or -name "conf.py")
> src_files_html := $(shell find ../static/ ../templates/ -type f)
>
> (This would replace the respective lists of files in
> share/doc/build/Makefile.am.)
>
> Anyone opposed to that?
>
> Cheers,
>
> Dirkjan
>
--
NS
Re: Getting rid of file lists in documentation Makefiles
Posted by Benoit Chesneau <bc...@gmail.com>.
On May 20, 2013 2:59 PM, "Dirkjan Ochtman" <di...@ochtman.nl> wrote:
>
> Hi there,
>
> Keeping Makefile.am in sync with the actual documentation is a PITA,
> and doesn't add any value. In fact, I broke the build over the weekend
> by not removing some files from the Makefiles. Instead, we can use
> invocations of find to find the relevant files in these cases:
>
> html_files := $(shell find ./html/ -type f -not -wholename "*doctree*"
> -not -name ".buildinfo")
> image_files := $(shell find ../images/ -type f)
> src_files := $(shell find ../src/ -name "*.rst" -or -name "conf.py")
> src_files_html := $(shell find ../static/ ../templates/ -type f)
>
> (This would replace the respective lists of files in
> share/doc/build/Makefile.am.)
>
> Anyone opposed to that?
>
> Cheers,
>
> Dirkjan
+1