You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@couchdb.apache.org by Alexander Shorin <kx...@gmail.com> on 2013/07/24 14:43:18 UTC
[REVIEW] Docs update
Hi all,
I'd finally stopped myself on continuously improving things that I
couldn't make ideally (:
Online preview version available at:
http://kxepal.iriscouch.com/docs/1.3/index.html
Changes:
- Base skeleton for future articles;
- Install guides for Unix, Windows, Gentoo and FreeBSD (as an example
and to provoke contribute more guides);
- Complete configuration reference;
- Refactor API reference (but still more work ahead);
- Replication protocol and conflicts;
- Query server protocol;
- Fauxton docs (from master branch);
- Guide to Externals API by Paul Davis;
- Intoduction into views: basics, collations, joins, for sql-people;
- Single internal reference system;
- "Show and Edit on GitHub" at sidebar - contributing fixes and
improvements never was so simple;
- Some things I'd forgotten.
Will be glad for quick spell and language check for configuration
reference and query server protocol.
--
,,,^..^,,,
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
Re: [REVIEW] Docs update
Posted by Noah Slater <ns...@apache.org>.
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 Filippo Fadda <fi...@programmazione.it>.
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
Re: [REVIEW] Docs update
Posted by Alexander Shorin <kx...@gmail.com>.
On Thu, Jul 25, 2013 at 4:16 AM, Filippo Fadda
<fi...@programmazione.it> wrote:
> On Jul 25, 2013, at 12:44 AM, Alexander Shorin wrote:
>> That's why installation guides (from sources, using system package
>> manager etc.) have to be in docs.
>
> I'm not telling they shouldn't be there, I'm telling, in the doc, you want find all:
>
> - Mac OS X
> Download the image (with the link to download)
> Install using MacPorts
> Install using Brew
>
> - Linux
> Install using apt-get (Ubuntu, Debian)
> Install using yum (CentOS, RedHat, Fedora)
> Gentoo (someone still use Gentoo? Maybe the same one is using Ruby) :-)
> etc.
>
> - Windows
> Download the installation package
>
> - You are a geek? Install from source! (here you can talk about dependencies and all that stuff)
>
> I know how to install it, that's not the point. I'm making the devil's advocate. If I'm a Mac OS X user, there is no way to know that I can install it from MacPorts unless reading the wiki. Maybe I just read the documentation, and I can't find, in the doc, there is an image to install it. I want read the manual, I want navigate to the Install section, choose Mac OS X, and learn all the ways to install it.
> The manual should teach you all, but it doesn't. I read it and I say: oh fuck, all those steps to install CouchDB on a *nix system?
Fair point, I got it. Thanks!
>> You got the point, but from the opposite side (: Content is moving
>> from wiki to docs in wiki is been deprecated in favour of docs.
>
> And this is good. But when the doc is updated with the wiki content, there is no reason to keep the same information there.
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.
> Just to be clear, I have nothing against you, I'm just suggesting some improvements because I think they can make a difference. In my opinion the documentation is fundamental.
No worries, moar critics and ideas! (: Thanks (:
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 (;
--
,,,^..^,,,
Re: [REVIEW] Docs update
Posted by Filippo Fadda <fi...@programmazione.it>.
On Jul 25, 2013, at 12:44 AM, Alexander Shorin wrote:
> That's why installation guides (from sources, using system package
> manager etc.) have to be in docs.
I'm not telling they shouldn't be there, I'm telling, in the doc, you want find all:
- Mac OS X
Download the image (with the link to download)
Install using MacPorts
Install using Brew
- Linux
Install using apt-get (Ubuntu, Debian)
Install using yum (CentOS, RedHat, Fedora)
Gentoo (someone still use Gentoo? Maybe the same one is using Ruby) :-)
etc.
- Windows
Download the installation package
- You are a geek? Install from source! (here you can talk about dependencies and all that stuff)
I know how to install it, that's not the point. I'm making the devil's advocate. If I'm a Mac OS X user, there is no way to know that I can install it from MacPorts unless reading the wiki. Maybe I just read the documentation, and I can't find, in the doc, there is an image to install it. I want read the manual, I want navigate to the Install section, choose Mac OS X, and learn all the ways to install it.
The manual should teach you all, but it doesn't. I read it and I say: oh fuck, all those steps to install CouchDB on a *nix system?
> Hm...the content is from:
> https://github.com/apache/couchdb/blob/master/INSTALL.Unix
> I hadn't add something from myself except formatting (:
I'm not telling that you are guilty, I'm suggesting how to improve the doc to make it useful for newbies, that's all. Unfortunately I can't help, because I'm really busy working on the ElephantOnCouch suite and rebuilding my site. This is my way to help, making suggestions; if you think I'm wrong you can simply ignore them, I'm just a user like many others.
> You got the point, but from the opposite side (: Content is moving
> from wiki to docs in wiki is been deprecated in favour of docs.
And this is good. But when the doc is updated with the wiki content, there is no reason to keep the same information there.
> Community still be able to easy contribute stuff with easy (see Edit
> on Github link on sidebar) without need to request registration
> permission, deal with some Moin-Moin systems etc.
This is what I said before in fact. I can simply edit and make a pull request on GitHub, instead I can't change the wiki content, and I don't wanna do it, because I think that wiki should disappear.
Just to be clear, I have nothing against you, I'm just suggesting some improvements because I think they can make a difference. In my opinion the documentation is fundamental.
Cheers
-Filippo
Re: [REVIEW] Docs update
Posted by Alexander Shorin <kx...@gmail.com>.
Hi Filippo,
Thanks for feedback!
> I don't understand why the installation section is so much complicated. You just need a command to install CouchDB on the most Linux distro or Mac OS X. To understand that, a user have to read also the "Community installation guides" present in the wiki.
> Moreover, I really don't know why I should use brew to install CouchDB on Mac OS X when it's available through MacPorts. I mean, brew is Ruby and Ruby sucks, like everyone knows. :-) OK, brew can be an option, but why the main or the only option?
The motivation:
0. You'd like to install CouchDB
1. Probably, you had already visited
https://couchdb.apache.org/#download and found available binaries for
Windows and MacOS. So in 80% of cases you have not to build them by
your own.
2. However, these are not your OS and you'd like to see guide for it.
There are two options:
1. You google "CouchDB 1.3 install Ubuntu"
2. You just open __official__ documentation
The first way shows you a lot of guides, even video instructions on
youtube. A lot of posts about how to install CouchDB of the latest
version on Ubuntu using different ways to go. But. Why the hell I have
to use third party sources if there is __official__ documentation? Can
I trust them? Will they be available tomorrow, when I'll be at work
and will try to follow provided guides?
The second way is just to read the docs. The wiki is good place for
community and the most recent guides, but it __always__ the latest.
There is no way to fix some guide for some specific CouchDB release
without making article big. Take a look on Ubuntu guide:
http://wiki.apache.org/couchdb/Installing_on_Ubuntu
It covers many of OS versions for many of CouchDB versions and, now,
all of them out of dated and useless, but still we have to keep them
for 20% of cases when people have older OS.
That's why installation guides (from sources, using system package
manager etc.) have to be in docs.
> The documentation says: "A high-level guide to Unix-like systems, inc. Mac OS X and Ubuntu." I really don't see the high level there, in fact it's very detailed, it teaches how-to compile it. As final user I'm just interested to install it, I don't care about to compile things from scratch or install dependencies, because probably yum, apt-get or port will do it automatically.
Hm...the content is from:
https://github.com/apache/couchdb/blob/master/INSTALL.Unix
I hadn't add something from myself except formatting (:
> Sincerely, I don't really think is a good idea having a wiki with the same contents of the manual. Why not just have a good manual and remove that wiki? All the relevant wiki contents should be assimilated into the manual to improve it and have a single start point.
> PHP does have a wiki? MySQL does have a wiki? Why don't merge the wiki with the manual, just like you are merging BigCouch into CouchDB? :-)
> Don't tell me that everyone can contribute to the wiki, because that's not true, you need credentials to do that, instead everyone can pull a request to modify the manual.
You got the point, but from the opposite side (: Content is moving
from wiki to docs in wiki is been deprecated in favour of docs.
Community still be able to easy contribute stuff with easy (see Edit
on Github link on sidebar) without need to request registration
permission, deal with some Moin-Moin systems etc.
In same way you could say for Guide to CouchDB: it also going to be
merged with docs, like BigCouch into CouchDB(:
--
,,,^..^,,,
Re: [REVIEW] Docs update
Posted by Filippo Fadda <fi...@programmazione.it>.
Hi Alexander,
glad to know about changes, but...
I don't understand why the installation section is so much complicated. You just need a command to install CouchDB on the most Linux distro or Mac OS X. To understand that, a user have to read also the "Community installation guides" present in the wiki.
Moreover, I really don't know why I should use brew to install CouchDB on Mac OS X when it's available through MacPorts. I mean, brew is Ruby and Ruby sucks, like everyone knows. :-) OK, brew can be an option, but why the main or the only option?
The documentation says: "A high-level guide to Unix-like systems, inc. Mac OS X and Ubuntu." I really don't see the high level there, in fact it's very detailed, it teaches how-to compile it. As final user I'm just interested to install it, I don't care about to compile things from scratch or install dependencies, because probably yum, apt-get or port will do it automatically.
Sincerely, I don't really think is a good idea having a wiki with the same contents of the manual. Why not just have a good manual and remove that wiki? All the relevant wiki contents should be assimilated into the manual to improve it and have a single start point.
PHP does have a wiki? MySQL does have a wiki? Why don't merge the wiki with the manual, just like you are merging BigCouch into CouchDB? :-)
Don't tell me that everyone can contribute to the wiki, because that's not true, you need credentials to do that, instead everyone can pull a request to modify the manual.
I know you are doing your best, I'm just suggesting a way to improve, IMHO.
Thx
-Filippo
On Jul 24, 2013, at 2:43 PM, Alexander Shorin wrote:
> Hi all,
>
> I'd finally stopped myself on continuously improving things that I
> couldn't make ideally (:
>
> Online preview version available at:
>
> http://kxepal.iriscouch.com/docs/1.3/index.html
>
> Changes:
>
> - Base skeleton for future articles;
> - Install guides for Unix, Windows, Gentoo and FreeBSD (as an example
> and to provoke contribute more guides);
> - Complete configuration reference;
> - Refactor API reference (but still more work ahead);
> - Replication protocol and conflicts;
> - Query server protocol;
> - Fauxton docs (from master branch);
> - Guide to Externals API by Paul Davis;
> - Intoduction into views: basics, collations, joins, for sql-people;
> - Single internal reference system;
> - "Show and Edit on GitHub" at sidebar - contributing fixes and
> improvements never was so simple;
> - Some things I'd forgotten.
>
> Will be glad for quick spell and language check for configuration
> reference and query server protocol.
>
> --
> ,,,^..^,,,