You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@couchdb.apache.org by Noah Slater <ns...@apache.org> on 2013/08/05 20:01:26 UTC
Re: [REVIEW] Docs update
Alexander,
This is freakin fantastic! Thank you so much!
Some comments:
Filippo has a point. Let's have a dead simple section that covers how to
install CouchDB in binary form.
For OS X, we should recommend the official binary download. And for a more
advanced setup, we should recommend Homebrew. For Linux, let's list a few
common options. Ubuntu, Debian, RedHat, and so on. For Windows, we can
point to the official binary downloads.
Then, we can keep the existing content as a "how to install from source"
info. That info is still very valuable, and should not be removed. But most
users are going to want a "how to install in 30 seconds" guide. And for
that reason, the binary install methods take precedence.
MacPorts is a POS. We should completely avoid mentioning it. (Both in the
binary install section, and in the source install section.)
The CouchDB documentation should be removed from the wiki when we have
added it to the docs. We can put in redirects, or just replace the content
with a hyperlink that takes you to the correct part of the most recent
hosted documentation.
However: please remember that the wiki is not going anywhere. There is
still a whole bunch of content that is suitable for the wiki and not
suitable for the docs. Things to do with community management, release
management, marketing, and so on.
Alexander: again, this is looking so great! Thank you for driving this!
On 25 July 2013 02:28, Filippo Fadda <fi...@programmazione.it>wrote:
>
> On Jul 25, 2013, at 2:38 AM, Alexander Shorin wrote:
> > To keep there - you mean wiki? At this you're also right: once docs be
> > merged with master, wiki content have to redirect to docs for some
> > time before fade away.
>
> Good to know. :-)
>
> > P.S. I also will be glad if you take a look on query server protocol
> > and say what you think about:
> > http://kxepal.iriscouch.com/docs/1.3/query-server/protocol.html
> > As the developer of php query server I believe you have your own view
> about (;
>
> I still have to implement the parts related to ddoc, show, list, and
> filter on both query server and client. So I'm glad to have a start point
> for them. I will read the doc and I will give you a feedback in the next
> days. And by the way you're all doing a great job with CouchDB. :-)
>
> Thanks
>
> -Filippo
--
Noah Slater
https://twitter.com/nslater
Re: [REVIEW] Docs update
Posted by Noah Slater <ns...@apache.org>.
Cool, thanks.
On 21 August 2013 20:29, Alexander Shorin <kx...@gmail.com> wrote:
> On Wed, Aug 21, 2013 at 10:44 PM, Noah Slater <ns...@apache.org> wrote:
> > This reminds me again. Alexander, would you be happy managing the merging
> > in the rest of CouchDB TDG? If so, I should kick off the IP Clearance
> soon
> > I think. At that point, we'd be free to remove the copyright notice from
> > NOTICE.
>
> Yes, I would! CouchDB TDG has awesome user-friendly content that docs
> must have too, so if it's possible, passing them through IP Clearance
> will be helpful.
>
> --
> ,,,^..^,,,
>
--
Noah Slater
https://twitter.com/nslater
Re: [REVIEW] Docs update
Posted by Alexander Shorin <kx...@gmail.com>.
Ok, will do(: Thank you!
--
,,,^..^,,,
On Thu, Aug 22, 2013 at 2:46 AM, Noah Slater <ns...@apache.org> wrote:
> P.S. Feel free to bug me if you don't see me making progress.
>
>
> On 21 August 2013 20:29, Alexander Shorin <kx...@gmail.com> wrote:
>
>> On Wed, Aug 21, 2013 at 10:44 PM, Noah Slater <ns...@apache.org> wrote:
>> > This reminds me again. Alexander, would you be happy managing the merging
>> > in the rest of CouchDB TDG? If so, I should kick off the IP Clearance
>> soon
>> > I think. At that point, we'd be free to remove the copyright notice from
>> > NOTICE.
>>
>> Yes, I would! CouchDB TDG has awesome user-friendly content that docs
>> must have too, so if it's possible, passing them through IP Clearance
>> will be helpful.
>>
>> --
>> ,,,^..^,,,
>>
>
>
>
> --
> Noah Slater
> https://twitter.com/nslater
Re: [REVIEW] Docs update
Posted by Noah Slater <ns...@apache.org>.
P.S. Feel free to bug me if you don't see me making progress.
On 21 August 2013 20:29, Alexander Shorin <kx...@gmail.com> wrote:
> On Wed, Aug 21, 2013 at 10:44 PM, Noah Slater <ns...@apache.org> wrote:
> > This reminds me again. Alexander, would you be happy managing the merging
> > in the rest of CouchDB TDG? If so, I should kick off the IP Clearance
> soon
> > I think. At that point, we'd be free to remove the copyright notice from
> > NOTICE.
>
> Yes, I would! CouchDB TDG has awesome user-friendly content that docs
> must have too, so if it's possible, passing them through IP Clearance
> will be helpful.
>
> --
> ,,,^..^,,,
>
--
Noah Slater
https://twitter.com/nslater
Re: [REVIEW] Docs update
Posted by Alexander Shorin <kx...@gmail.com>.
On Wed, Aug 21, 2013 at 10:44 PM, Noah Slater <ns...@apache.org> wrote:
> This reminds me again. Alexander, would you be happy managing the merging
> in the rest of CouchDB TDG? If so, I should kick off the IP Clearance soon
> I think. At that point, we'd be free to remove the copyright notice from
> NOTICE.
Yes, I would! CouchDB TDG has awesome user-friendly content that docs
must have too, so if it's possible, passing them through IP Clearance
will be helpful.
--
,,,^..^,,,
Re: [REVIEW] Docs update
Posted by Noah Slater <ns...@apache.org>.
This reminds me again. Alexander, would you be happy managing the merging
in the rest of CouchDB TDG? If so, I should kick off the IP Clearance soon
I think. At that point, we'd be free to remove the copyright notice from
NOTICE.
On 21 August 2013 18:28, Jan Lehnardt <ja...@apache.org> wrote:
>
> On Aug 21, 2013, at 19:22 , Alexander Shorin <kx...@gmail.com> wrote:
>
> > On Wed, Aug 21, 2013 at 2:03 PM, Jan Lehnardt <ja...@apache.org> wrote:
> >> I went through all commits in the branch and cleaned up a few language
> and grammar nits that I just committed. Overall this is totally awesome,
> thanks so much for your effort!
> >>
> >> You imported a few parts from guide.couchdb.org and a blog post by
> Christopher Lenz. We need to make sure to attribute these correctly in our
> NOTICE file. For the guide, there isn’t a big issue, we just need to
> mention its Creative Commons license and we best just email Christopher and
> ask if he’s cool with adding his post.
> >
> > I'd mailed Christopher about copyrights. Hope he'll make response soon.
>
> Thanks :)
>
> > For CouchDB Guide do I have list all files with his content and what
> > copyright line should be? Is it enough to have:
> >
> > * share/doc/src/foo/bar.rst share/doc/src/foo/baz.rst
> share/doc/src/foo/boo.rst
> >
> > Creative Commons Attribution license.
>
> Yeah, t hat would be easiest.
>
> >> Are there any other external sources you borrowed from?
> >
> > There are:
> >
> > Externals API by Paul Davis (N.B. refactor it a bit)
> >
> https://github.com/apache/couchdb/blob/1781-reorganize-and-improve-docs/share/doc/src/externals.rst
> > Source: http://davispj.com/2010/09/26/new-couchdb-externals-api.html
> >
> > Replication Protocol by Benoitc
> >
> https://github.com/apache/couchdb/blob/1781-reorganize-and-improve-docs/share/doc/src/replication/protocol.rst
> > Source: http://www.dataprotocols.org/en/latest/couchdb_replication.html
>
> I assume these two are fine for integrating, but no harm in getting a +1
> from Paul and Benoit here :)
>
>
> > Sphinx httpdomain extension
> >
> https://github.com/apache/couchdb/blob/1781-reorganize-and-improve-docs/share/doc/ext/httpdomain.py
> > Source:
> https://bitbucket.org/birkenfeld/sphinx-contrib/src/a94e8149babc860d0bf18ff6ea7521ecfce0b43b/httpdomain/sphinxcontrib/httpdomain.py
> > However, it's heavy modified for our needs and doesn't backward
> compatible
>
> Definitely needs attribution.
>
> > + a lot of Wiki content
>
> Excellent, thanks!
>
> Jan
> --
>
>
--
Noah Slater
https://twitter.com/nslater
Re: [REVIEW] Docs update
Posted by Jan Lehnardt <ja...@apache.org>.
On Aug 21, 2013, at 19:22 , Alexander Shorin <kx...@gmail.com> wrote:
> On Wed, Aug 21, 2013 at 2:03 PM, Jan Lehnardt <ja...@apache.org> wrote:
>> I went through all commits in the branch and cleaned up a few language and grammar nits that I just committed. Overall this is totally awesome, thanks so much for your effort!
>>
>> You imported a few parts from guide.couchdb.org and a blog post by Christopher Lenz. We need to make sure to attribute these correctly in our NOTICE file. For the guide, there isn’t a big issue, we just need to mention its Creative Commons license and we best just email Christopher and ask if he’s cool with adding his post.
>
> I'd mailed Christopher about copyrights. Hope he'll make response soon.
Thanks :)
> For CouchDB Guide do I have list all files with his content and what
> copyright line should be? Is it enough to have:
>
> * share/doc/src/foo/bar.rst share/doc/src/foo/baz.rst share/doc/src/foo/boo.rst
>
> Creative Commons Attribution license.
Yeah, t hat would be easiest.
>> Are there any other external sources you borrowed from?
>
> There are:
>
> Externals API by Paul Davis (N.B. refactor it a bit)
> https://github.com/apache/couchdb/blob/1781-reorganize-and-improve-docs/share/doc/src/externals.rst
> Source: http://davispj.com/2010/09/26/new-couchdb-externals-api.html
>
> Replication Protocol by Benoitc
> https://github.com/apache/couchdb/blob/1781-reorganize-and-improve-docs/share/doc/src/replication/protocol.rst
> Source: http://www.dataprotocols.org/en/latest/couchdb_replication.html
I assume these two are fine for integrating, but no harm in getting a +1 from Paul and Benoit here :)
> Sphinx httpdomain extension
> https://github.com/apache/couchdb/blob/1781-reorganize-and-improve-docs/share/doc/ext/httpdomain.py
> Source: https://bitbucket.org/birkenfeld/sphinx-contrib/src/a94e8149babc860d0bf18ff6ea7521ecfce0b43b/httpdomain/sphinxcontrib/httpdomain.py
> However, it's heavy modified for our needs and doesn't backward compatible
Definitely needs attribution.
> + a lot of Wiki content
Excellent, thanks!
Jan
--
Re: [REVIEW] Docs update
Posted by Alexander Shorin <kx...@gmail.com>.
On Wed, Aug 21, 2013 at 2:03 PM, Jan Lehnardt <ja...@apache.org> wrote:
> I went through all commits in the branch and cleaned up a few language and grammar nits that I just committed. Overall this is totally awesome, thanks so much for your effort!
>
> You imported a few parts from guide.couchdb.org and a blog post by Christopher Lenz. We need to make sure to attribute these correctly in our NOTICE file. For the guide, there isn’t a big issue, we just need to mention its Creative Commons license and we best just email Christopher and ask if he’s cool with adding his post.
I'd mailed Christopher about copyrights. Hope he'll make response soon.
For CouchDB Guide do I have list all files with his content and what
copyright line should be? Is it enough to have:
* share/doc/src/foo/bar.rst share/doc/src/foo/baz.rst share/doc/src/foo/boo.rst
Creative Commons Attribution license.
> Are there any other external sources you borrowed from?
There are:
Externals API by Paul Davis (N.B. refactor it a bit)
https://github.com/apache/couchdb/blob/1781-reorganize-and-improve-docs/share/doc/src/externals.rst
Source: http://davispj.com/2010/09/26/new-couchdb-externals-api.html
Replication Protocol by Benoitc
https://github.com/apache/couchdb/blob/1781-reorganize-and-improve-docs/share/doc/src/replication/protocol.rst
Source: http://www.dataprotocols.org/en/latest/couchdb_replication.html
Sphinx httpdomain extension
https://github.com/apache/couchdb/blob/1781-reorganize-and-improve-docs/share/doc/ext/httpdomain.py
Source: https://bitbucket.org/birkenfeld/sphinx-contrib/src/a94e8149babc860d0bf18ff6ea7521ecfce0b43b/httpdomain/sphinxcontrib/httpdomain.py
However, it's heavy modified for our needs and doesn't backward compatible
+ a lot of Wiki content
--
,,,^..^,,,
Re: [REVIEW] Docs update
Posted by Jan Lehnardt <ja...@apache.org>.
Heya Alex,
I went through all commits in the branch and cleaned up a few language and grammar nits that I just committed. Overall this is totally awesome, thanks so much for your effort!
You imported a few parts from guide.couchdb.org and a blog post by Christopher Lenz. We need to make sure to attribute these correctly in our NOTICE file. For the guide, there isn’t a big issue, we just need to mention its Creative Commons license and we best just email Christopher and ask if he’s cool with adding his post. Are there any other external sources you borrowed from?
FWIW, I wrote a follow up on “CouchDB Joins” a few years later: https://gist.github.com/janl/6292622 feel free to copy anything from there :)
Once NOTICE is up to date, I feel comfortable to merge this into master.
Again, great job, thanks!
Best
Jan
--
On Aug 19, 2013, at 12:35 , Alexander Shorin <kx...@gmail.com> wrote:
> On Sun, Aug 18, 2013 at 8:02 PM, Dirkjan Ochtman <di...@ochtman.nl> wrote:
>> On Fri, Aug 9, 2013 at 11:10 AM, Alexander Shorin <kx...@gmail.com> wrote:
>>> Hope to finish some few base things till 1.4 votes (thanks for Dirkjan
>>> vacations, it's not too late for docs updates, right?) before merge
>>> it.
>>
>> I'd like to do a thorough review of your branch, ideally before it
>> gets merged (though it might not matter much).
>
> Sure, will be glad you for that(:
>
> I'll push final updates today at night, but they don't changes current stuff.
>
> --
> ,,,^..^,,,
Re: [REVIEW] Docs update
Posted by Alexander Shorin <kx...@gmail.com>.
On Sun, Aug 18, 2013 at 8:02 PM, Dirkjan Ochtman <di...@ochtman.nl> wrote:
> On Fri, Aug 9, 2013 at 11:10 AM, Alexander Shorin <kx...@gmail.com> wrote:
>> Hope to finish some few base things till 1.4 votes (thanks for Dirkjan
>> vacations, it's not too late for docs updates, right?) before merge
>> it.
>
> I'd like to do a thorough review of your branch, ideally before it
> gets merged (though it might not matter much).
Sure, will be glad you for that(:
I'll push final updates today at night, but they don't changes current stuff.
--
,,,^..^,,,
Re: [REVIEW] Docs update
Posted by Dirkjan Ochtman <di...@ochtman.nl>.
On Fri, Aug 9, 2013 at 11:10 AM, Alexander Shorin <kx...@gmail.com> wrote:
> Hope to finish some few base things till 1.4 votes (thanks for Dirkjan
> vacations, it's not too late for docs updates, right?) before merge
> it.
I'd like to do a thorough review of your branch, ideally before it
gets merged (though it might not matter much).
Cheers,
Dirkjan
Re: [REVIEW] Docs update
Posted by Noah Slater <ns...@apache.org>.
Octavian, what do you think about:
https://github.com/iriscouch/build-couchdb
On 13 August 2013 09:58, Octavian Damiean <od...@linux.com> wrote:
> On Fri, Aug 9, 2013 at 4:04 PM, Filippo Fadda <
> filippo.fadda@programmazione.it> wrote:
>
> > Actually the Installation of "Unix-like systems" is full of "you are
> > driving me crazy" things.
> > I didn't try, but I'm pretty sure to install on RedHat, CentOS, Fedora
> you
> > just need "yum install couchdb" like "apt-get install couchdb" on Debian
> > style distro like Ubuntu. Let's apply the KIS principle, even to the
> > documentation.
> >
> > It's OK having a detailed section that list all the dependencies but
> > that's something, probably, used only by developers or people having
> > troubles on their systems. So, also the UNIX section should be revised
> with
> > the minimum required steps to install CouchDB on the various distro.
> > All the Unix stuff should be moved to "Install from source" section,
> where
> > find all the dependencies you need to compile CouchDB, tips and tricks,
> etc.
>
>
> It's really not that simple. For the bleeding edge distros a package
> manager solution might be enough, as they might have CouchDB in a
> relatively new version in their repository but most don't.
>
> Here is the current CouchDB version situation in different distros and
> versions of that distro.
>
> Arch Linux: 1.4.0
> Debian Wheezy (stable): 1.2.0
> Debian Jessie (testing): 1.2.0
> Debian Sid (unstable): 1.2.0
> Fedora 18: 1.2.1
> Fedora 19: 1.2.2
> Ubuntu 12.04 Precise Pangolin: 1.0.1
> Ubuntu 12.10 Quantal Quetzal: 1.2.0
> Ubuntu 13.04 Raring Ringtail: 1.2.0
> Ubuntu 13.10 Saucy Salamander (still in development, might change): 1.2.0
>
> So the overall picture doesn't look that good to me. None of those
> distributions provide an up-to-date stable version of CouchDB, only Arch
> Linux provides a bleeding edge version which is better than nothing but
> still not really satisfying in my opinion.
>
> The build from source procedures are required and we should probably try to
> create a build tool like the Mozilla guys have for Firefox. I'm talking
> about "mach" if anyone is wondering. That tools makes it really easy to
> build from source using one command.
>
> Just my 2cents on the Linux part as that's pretty much my area of
> expertise.
>
> Cheers,
> --
> Octavian Damiean
>
> GitHub: https://github.com/mainerror
>
--
Noah Slater
https://twitter.com/nslater
Re: [REVIEW] Docs update
Posted by Octavian Damiean <od...@linux.com>.
On Fri, Aug 9, 2013 at 4:04 PM, Filippo Fadda <
filippo.fadda@programmazione.it> wrote:
> Actually the Installation of "Unix-like systems" is full of "you are
> driving me crazy" things.
> I didn't try, but I'm pretty sure to install on RedHat, CentOS, Fedora you
> just need "yum install couchdb" like "apt-get install couchdb" on Debian
> style distro like Ubuntu. Let's apply the KIS principle, even to the
> documentation.
>
> It's OK having a detailed section that list all the dependencies but
> that's something, probably, used only by developers or people having
> troubles on their systems. So, also the UNIX section should be revised with
> the minimum required steps to install CouchDB on the various distro.
> All the Unix stuff should be moved to "Install from source" section, where
> find all the dependencies you need to compile CouchDB, tips and tricks, etc.
It's really not that simple. For the bleeding edge distros a package
manager solution might be enough, as they might have CouchDB in a
relatively new version in their repository but most don't.
Here is the current CouchDB version situation in different distros and
versions of that distro.
Arch Linux: 1.4.0
Debian Wheezy (stable): 1.2.0
Debian Jessie (testing): 1.2.0
Debian Sid (unstable): 1.2.0
Fedora 18: 1.2.1
Fedora 19: 1.2.2
Ubuntu 12.04 Precise Pangolin: 1.0.1
Ubuntu 12.10 Quantal Quetzal: 1.2.0
Ubuntu 13.04 Raring Ringtail: 1.2.0
Ubuntu 13.10 Saucy Salamander (still in development, might change): 1.2.0
So the overall picture doesn't look that good to me. None of those
distributions provide an up-to-date stable version of CouchDB, only Arch
Linux provides a bleeding edge version which is better than nothing but
still not really satisfying in my opinion.
The build from source procedures are required and we should probably try to
create a build tool like the Mozilla guys have for Firefox. I'm talking
about "mach" if anyone is wondering. That tools makes it really easy to
build from source using one command.
Just my 2cents on the Linux part as that's pretty much my area of expertise.
Cheers,
--
Octavian Damiean
GitHub: https://github.com/mainerror
Re: [REVIEW] Docs update
Posted by Noah Slater <ns...@apache.org>.
I like the idea of all the complex stuff being moved to an "Install from
source" section, which is kept as the last thing we mention.
Alexander, I think you still have time to work on the docs before Dirkjan
is back, yep!
On 9 August 2013 15:04, Filippo Fadda <fi...@programmazione.it>wrote:
> Done.
>
> I don't know much about Homebrew, but it seems to me that you don't need
> all the steps described to install CouchDB from brew.
> Someone should also revise the Homebrew section.
>
> Actually the Installation of "Unix-like systems" is full of "you are
> driving me crazy" things.
> I didn't try, but I'm pretty sure to install on RedHat, CentOS, Fedora you
> just need "yum install couchdb" like "apt-get install couchdb" on Debian
> style distro like Ubuntu. Let's apply the KIS principle, even to the
> documentation.
>
> It's OK having a detailed section that list all the dependencies but
> that's something, probably, used only by developers or people having
> troubles on their systems. So, also the UNIX section should be revised with
> the minimum required steps to install CouchDB on the various distro.
> All the Unix stuff should be moved to "Install from source" section, where
> find all the dependencies you need to compile CouchDB, tips and tricks, etc.
>
> -Filippo
>
> On Aug 9, 2013, at 11:10 AM, Alexander Shorin wrote:
>
> > On Fri, Aug 9, 2013 at 12:27 PM, Dave Cottlehuber <dc...@jsonified.com>
> wrote:
> >>> I agree, dmg is the first choice for everyone, but if CouchDB is
> available through MacPorts, Fink, Homebrew or even Rudix who do not mention
> them?
> >>
> >> +1. Let's make it as easy as pie to get on the couch.
> >>
> >> Filippo, would you like to send in a patch to update these?
> >> https://github.com/apache/couchdb/tree/master/share/doc/src and how-to
> >> is here
> https://github.com/apache/couchdb/blob/master/share/doc/src/contributing.rst
> >> should cover how to do this.
> >>
> >
> > Better to send it against:
> >
> https://github.com/apache/couchdb/tree/1781-reorganize-and-improve-docs/share/doc/src
> >
> > There is special article about Mac installation, so it would be easy
> > to concentrate on the problem to provide better content.
> > Also, while you're reading docs at my local mirror, you may hit "Edit
> > on GitHub" button to quick send PR with fixes.
> >
> > Hope to finish some few base things till 1.4 votes (thanks for Dirkjan
> > vacations, it's not too late for docs updates, right?) before merge
> > it.
> >
> > --
> > ,,,^..^,,,
>
>
--
Noah Slater
https://twitter.com/nslater
Re: [REVIEW] Docs update
Posted by Filippo Fadda <fi...@programmazione.it>.
Done.
I don't know much about Homebrew, but it seems to me that you don't need all the steps described to install CouchDB from brew.
Someone should also revise the Homebrew section.
Actually the Installation of "Unix-like systems" is full of "you are driving me crazy" things.
I didn't try, but I'm pretty sure to install on RedHat, CentOS, Fedora you just need "yum install couchdb" like "apt-get install couchdb" on Debian style distro like Ubuntu. Let's apply the KIS principle, even to the documentation.
It's OK having a detailed section that list all the dependencies but that's something, probably, used only by developers or people having troubles on their systems. So, also the UNIX section should be revised with the minimum required steps to install CouchDB on the various distro.
All the Unix stuff should be moved to "Install from source" section, where find all the dependencies you need to compile CouchDB, tips and tricks, etc.
-Filippo
On Aug 9, 2013, at 11:10 AM, Alexander Shorin wrote:
> On Fri, Aug 9, 2013 at 12:27 PM, Dave Cottlehuber <dc...@jsonified.com> wrote:
>>> I agree, dmg is the first choice for everyone, but if CouchDB is available through MacPorts, Fink, Homebrew or even Rudix who do not mention them?
>>
>> +1. Let's make it as easy as pie to get on the couch.
>>
>> Filippo, would you like to send in a patch to update these?
>> https://github.com/apache/couchdb/tree/master/share/doc/src and how-to
>> is here https://github.com/apache/couchdb/blob/master/share/doc/src/contributing.rst
>> should cover how to do this.
>>
>
> Better to send it against:
> https://github.com/apache/couchdb/tree/1781-reorganize-and-improve-docs/share/doc/src
>
> There is special article about Mac installation, so it would be easy
> to concentrate on the problem to provide better content.
> Also, while you're reading docs at my local mirror, you may hit "Edit
> on GitHub" button to quick send PR with fixes.
>
> Hope to finish some few base things till 1.4 votes (thanks for Dirkjan
> vacations, it's not too late for docs updates, right?) before merge
> it.
>
> --
> ,,,^..^,,,
Re: [REVIEW] Docs update
Posted by Alexander Shorin <kx...@gmail.com>.
On Fri, Aug 9, 2013 at 12:27 PM, Dave Cottlehuber <dc...@jsonified.com> wrote:
>> I agree, dmg is the first choice for everyone, but if CouchDB is available through MacPorts, Fink, Homebrew or even Rudix who do not mention them?
>
> +1. Let's make it as easy as pie to get on the couch.
>
> Filippo, would you like to send in a patch to update these?
> https://github.com/apache/couchdb/tree/master/share/doc/src and how-to
> is here https://github.com/apache/couchdb/blob/master/share/doc/src/contributing.rst
> should cover how to do this.
>
Better to send it against:
https://github.com/apache/couchdb/tree/1781-reorganize-and-improve-docs/share/doc/src
There is special article about Mac installation, so it would be easy
to concentrate on the problem to provide better content.
Also, while you're reading docs at my local mirror, you may hit "Edit
on GitHub" button to quick send PR with fixes.
Hope to finish some few base things till 1.4 votes (thanks for Dirkjan
vacations, it's not too late for docs updates, right?) before merge
it.
--
,,,^..^,,,
Re: [REVIEW] Docs update
Posted by Dave Cottlehuber <dc...@jsonified.com>.
On 8 August 2013 15:28, Filippo Fadda <fi...@programmazione.it> wrote:
>
> On Aug 5, 2013, at 8:01 PM, Noah Slater wrote:
>> MacPorts is a POS. We should completely avoid mentioning it. (Both in the
>> binary install section, and in the source install section.)
>
> OMG, the POS is brew not MacPorts. All my system is installed around MacPorts, even Apache (sure I replaced the default installation, because Apple doesn't update it, and to load an extension you have to compile from source). I can upgrade all the PHP extensions, even PHP with a command. Homebrew is a package manager for Ruby tards.
While I'm happy to debate the general merits & preferences of various
tools, offensive language in any form has no place in our couchdb
community. Relax is our watchword :-).
> Homebrew simply doesn't offer the same amount of packages you can find on MacPorts.
True.
> We can stay all day to discuss which is the best (MacPorts), but we will never reach an agreement and we don't need. The fact is that you can't tell me a good reason to not mention MacPorts. MacPorts is the first Mac OS X open source repository and not only should be mentioned, but it should be mentioned before Homebrew.
I think that's a tad extremist, but I agree that there's no reason not
to add both port mgmt tools to the documentation. For a long time,
macports lagged both erlang and couchdb releases, and there was no
active maintenance, eg ssl was missing for a long time. That's
certainly changed, and that's a good thing.
>From a selfish committers perspective, I can say that couchdb works on
homebrew as I test it well before each release, and I use it to run &
test master pretty much all the time. I do know that getting changes
committed to the brew recipes for couchdb is taking longer & longer
for each release, which is not ideal. Nothing's ever perfect.
> I agree, dmg is the first choice for everyone, but if CouchDB is available through MacPorts, Fink, Homebrew or even Rudix who do not mention them?
+1. Let's make it as easy as pie to get on the couch.
Filippo, would you like to send in a patch to update these?
https://github.com/apache/couchdb/tree/master/share/doc/src and how-to
is here https://github.com/apache/couchdb/blob/master/share/doc/src/contributing.rst
should cover how to do this.
If we have an active & reachable maintainer for a given
platform/packaging tool then they should feel free to do the same. My
only request to maintainers is that if you have to patch couchdb to
work on your distro, *please* let us know, it's something we are very
likely to want to fix for everybody, properly.
A+
Dave
Re: [REVIEW] Docs update
Posted by Filippo Fadda <fi...@programmazione.it>.
On Aug 5, 2013, at 8:01 PM, Noah Slater wrote:
> MacPorts is a POS. We should completely avoid mentioning it. (Both in the
> binary install section, and in the source install section.)
OMG, the POS is brew not MacPorts. All my system is installed around MacPorts, even Apache (sure I replaced the default installation, because Apple doesn't update it, and to load an extension you have to compile from source). I can upgrade all the PHP extensions, even PHP with a command. Homebrew is a package manager for Ruby tards.
Homebrew simply doesn't offer the same amount of packages you can find on MacPorts.
We can stay all day to discuss which is the best (MacPorts), but we will never reach an agreement and we don't need. The fact is that you can't tell me a good reason to not mention MacPorts. MacPorts is the first Mac OS X open source repository and not only should be mentioned, but it should be mentioned before Homebrew.
I agree, dmg is the first choice for everyone, but if CouchDB is available through MacPorts, Fink, Homebrew or even Rudix who do not mention them?
-Filippo
Re: [REVIEW] Docs update
Posted by Alexander Shorin <kx...@gmail.com>.
Hi Noah!
On Mon, Aug 5, 2013 at 10:01 PM, Noah Slater <ns...@apache.org> wrote:
> Alexander,
>
> This is freakin fantastic! Thank you so much!
Thanks! (:
> Some comments:
>
> Filippo has a point. Let's have a dead simple section that covers how to
> install CouchDB in binary form.
Agreed.
> For OS X, we should recommend the official binary download. And for a more
> advanced setup, we should recommend Homebrew. For Linux, let's list a few
> common options. Ubuntu, Debian, RedHat, and so on. For Windows, we can
> point to the official binary downloads.
>
> Then, we can keep the existing content as a "how to install from source"
> info. That info is still very valuable, and should not be removed. But most
> users are going to want a "how to install in 30 seconds" guide. And for
> that reason, the binary install methods take precedence.
I'd updated Windows and Mac guides with first place suggesting to
download official release binaries:
http://kxepal.iriscouch.com/docs/1.3/install/windows.html
http://kxepal.iriscouch.com/docs/1.3/install/mac.html
Linux distros are coming - I need setup virtual boxes to reproduce all
steps before.
> MacPorts is a POS. We should completely avoid mentioning it. (Both in the
> binary install section, and in the source install section.)
Currently, I'd just mix INSTALL.Unix and wiki's
http://wiki.apache.org/couchdb/Installing_on_OSX
There was MacPorts guide and AFAIK there is some person that supports it.
But not really sure in result since I have no Mac to test it. Or if
someone suggest me how to install XCode on Hackintosh 10.7.3 (no
updates available) I would be also glad (:
> The CouchDB documentation should be removed from the wiki when we have
> added it to the docs. We can put in redirects, or just replace the content
> with a hyperlink that takes you to the correct part of the most recent
> hosted documentation.
Ok. I'll start track list of wiki's articles that will be superseeded by docs.
> However: please remember that the wiki is not going anywhere. There is
> still a whole bunch of content that is suitable for the wiki and not
> suitable for the docs. Things to do with community management, release
> management, marketing, and so on.
Sure.
> Alexander: again, this is looking so great! Thank you for driving this!
>
>
> On 25 July 2013 02:28, Filippo Fadda <fi...@programmazione.it>wrote:
>
>>
>> On Jul 25, 2013, at 2:38 AM, Alexander Shorin wrote:
>> > To keep there - you mean wiki? At this you're also right: once docs be
>> > merged with master, wiki content have to redirect to docs for some
>> > time before fade away.
>>
>> Good to know. :-)
>>
>> > P.S. I also will be glad if you take a look on query server protocol
>> > and say what you think about:
>> > http://kxepal.iriscouch.com/docs/1.3/query-server/protocol.html
>> > As the developer of php query server I believe you have your own view
>> about (;
>>
>> I still have to implement the parts related to ddoc, show, list, and
>> filter on both query server and client. So I'm glad to have a start point
>> for them. I will read the doc and I will give you a feedback in the next
>> days. And by the way you're all doing a great job with CouchDB. :-)
>>
>> Thanks
>>
>> -Filippo
>
>
>
>
> --
> Noah Slater
> https://twitter.com/nslater