Re: Documentation contributors guide

[Stefan Podkowinski]

As nobody seems to object, you can now find a patch for the proposed
document in the corresponding Jira ticket:
https://issues.apache.org/jira/browse/CASSANDRA-13256



On 03/17/2017 08:33 PM, Stefan Podkowinski wrote:
> There's recently been a discussion about the wiki and how we should
> continue to work on the documentation in general. One of my suggestions
> was to start giving users a clearer guideline how they are able to
> contribute to our documentation, before having a technical discussion
> around tools and wikis again.
> 
> I've now created a first version on such a guide that can be found here:
> https://github.com/spodkowinski/cassandra/blob/docs_gettingstarted/doc/source/development/documentation.rst
> 
> As you can see there's a large part about using GitHub for editing on
> the page. I'd like to know what you think about that and if you'd agree
> to accept PRs for such purposes.
> 
> I'd also like to add another section for committers that describes the
> required steps to actually publish the latest trunk to our website. I
> know that svn has been mentioned somewhere, but I would appreciate if
> someone either adds that section or just shares some details in this thread.
> 
> Cheers!
> 

Re: Documentation contributors guide

[Jeff Jirsa]

> > On 2017-03-17 12:33 (-0700), Stefan Podkowinski  wrote: 
> > 
> >> As you can see there's a large part about using GitHub for editing on
> >> the page. I'd like to know what you think about that and if you'd agree
> >> to accept PRs for such purposes.

I don't want to bury the important point in minutiae of actually committing:

Your doc/howto on docs is awesome. Much needed and welcome addition to the docs.

Re: Documentation contributors guide

[Jeff Jirsa]

On 2017-03-17 13:06 (-0700), benjamin roth  wrote: 
> Isn't there a way to script that with just a few lines of python or
> whatever?

For docs, probably. Real patches are harder.  

There's a minor problem that they're a bit spammy (all PRs create dev@ emails), 
but I'd rather tolerate that noise than discourage contributors, so I 
(personally, not sure if rest of the committers/PMC agree) encourage people to 
send Github PRs if it's the only way they can contribute.

Re: Documentation contributors guide

[Stefan Podkowinski]

I don't see how that would be harder compared to merging a patch
attached to a jira ticket. If you'd want to merge my PR you'd just have
to do something like that:

curl -o docs.patch
https://github.com/apache/cassandra/compare/trunk...spodkowinski:docs_gettingstarted.patch
git am docs.patch
git reset --soft origin/trunk
git commit (add proper commit message and a "Merges #" text to
automatically close the PR)



On 03/17/2017 09:03 PM, Jeff Jirsa wrote:
> 
> 
> On 2017-03-17 12:33 (-0700), Stefan Podkowinski  wrote: 
> 
>> As you can see there's a large part about using GitHub for editing on
>> the page. I'd like to know what you think about that and if you'd agree
>> to accept PRs for such purposes.
>>
> 
> The challenge of github PRs isn't that we don't want them, it's that we can't 
> merge them - the apache github repo is a read only mirror (the master is on 
> ASF infrastructure). 
> 
> Personally, I'd rather have a Github PR than no patch, but I'd much rather 
> have a JIRA patch than a Github PR, because ultimately the committer is going 
> to have to manually transform the Github PR into a .patch file and commit it 
> with a special commit message to close the Github PR (or hope that the 
> contributor closes it for us, because committers can't even close PRs at this 
> point). 
> 
>> I'd also like to add another section for committers that describes the
>> required steps to actually publish the latest trunk to our website. I
>> know that svn has been mentioned somewhere, but I would appreciate if
>> someone either adds that section or just shares some details in this thread.
> 
> The repo is at https://svn.apache.org/repos/asf/cassandra/ - there's a doc at 
> https://svn.apache.org/repos/asf/cassandra/site/src/README that describes it. 
> 

Re: Documentation contributors guide

[benjamin roth]

Isn't there a way to script that with just a few lines of python or
whatever?

2017-03-17 21:03 GMT+01:00 Jeff Jirsa :

>
>
> On 2017-03-17 12:33 (-0700), Stefan Podkowinski  wrote:
>
> > As you can see there's a large part about using GitHub for editing on
> > the page. I'd like to know what you think about that and if you'd agree
> > to accept PRs for such purposes.
> >
>
> The challenge of github PRs isn't that we don't want them, it's that we
> can't merge them - the apache github repo is a read only mirror (the master
> is on ASF infrastructure).
>
> Personally, I'd rather have a Github PR than no patch, but I'd much rather
> have a JIRA patch than a Github PR, because ultimately the committer is
> going to have to manually transform the Github PR into a .patch file and
> commit it with a special commit message to close the Github PR (or hope
> that the contributor closes it for us, because committers can't even close
> PRs at this point).
>
> > I'd also like to add another section for committers that describes the
> > required steps to actually publish the latest trunk to our website. I
> > know that svn has been mentioned somewhere, but I would appreciate if
> > someone either adds that section or just shares some details in this
> thread.
>
> The repo is at https://svn.apache.org/repos/asf/cassandra/ - there's a
> doc at https://svn.apache.org/repos/asf/cassandra/site/src/README that
> describes it.
>

Re: Documentation contributors guide

[Jeff Jirsa]

On 2017-03-17 12:33 (-0700), Stefan Podkowinski  wrote: 

> As you can see there's a large part about using GitHub for editing on
> the page. I'd like to know what you think about that and if you'd agree
> to accept PRs for such purposes.
> 

The challenge of github PRs isn't that we don't want them, it's that we can't 
merge them - the apache github repo is a read only mirror (the master is on ASF 
infrastructure). 

Personally, I'd rather have a Github PR than no patch, but I'd much rather have 
a JIRA patch than a Github PR, because ultimately the committer is going to 
have to manually transform the Github PR into a .patch file and commit it with 
a special commit message to close the Github PR (or hope that the contributor 
closes it for us, because committers can't even close PRs at this point). 

> I'd also like to add another section for committers that describes the
> required steps to actually publish the latest trunk to our website. I
> know that svn has been mentioned somewhere, but I would appreciate if
> someone either adds that section or just shares some details in this thread.

The repo is at https://svn.apache.org/repos/asf/cassandra/ - there's a doc at 
https://svn.apache.org/repos/asf/cassandra/site/src/README that describes it. 

Documentation contributors guide

[Stefan Podkowinski]

There's recently been a discussion about the wiki and how we should
continue to work on the documentation in general. One of my suggestions
was to start giving users a clearer guideline how they are able to
contribute to our documentation, before having a technical discussion
around tools and wikis again.

I've now created a first version on such a guide that can be found here:
https://github.com/spodkowinski/cassandra/blob/docs_gettingstarted/doc/source/development/documentation.rst

As you can see there's a large part about using GitHub for editing on
the page. I'd like to know what you think about that and if you'd agree
to accept PRs for such purposes.

I'd also like to add another section for committers that describes the
required steps to actually publish the latest trunk to our website. I
know that svn has been mentioned somewhere, but I would appreciate if
someone either adds that section or just shares some details in this thread.

Cheers!