Merging documentation in the main repository

classic Classic list List threaded Threaded
14 messages Options
Reply | Threaded
Open this post in threaded view
|

Merging documentation in the main repository

Marco Pivetta
Yes you heard me.

I don't know if this is a good idea, but it worked fine so far for the ORM, since we can now stop merges to happen without documentation.

Can anybody recap me on why the docs were moved out?
Reply | Threaded
Open this post in threaded view
|

Re: Merging documentation in the main repository

Stefano Torresi
This post has NOT been accepted by the mailing list yet.
CONTENTS DELETED
The author has deleted this message.
Reply | Threaded
Open this post in threaded view
|

Re: Merging documentation in the main repository

Eric Boh
In reply to this post by Marco Pivetta
Why is it not sufficient enough to reference from or to a documentation PR? 


2013/6/20 Marco Pivetta <[hidden email]>
Yes you heard me.

I don't know if this is a good idea, but it worked fine so far for the ORM, since we can now stop merges to happen without documentation.

Can anybody recap me on why the docs were moved out?

Reply | Threaded
Open this post in threaded view
|

Re: Merging documentation in the main repository

Marco Pivetta

On 20 June 2013 13:38, Eric Boh <[hidden email]> wrote:
Why is it not sufficient enough to reference from or to a documentation PR? 

@coss that requires a lot of cross-checking work.

One Merge to rule them all, One Merge to find them,One Merge to bring them all and in the darkness bind them

Really, it's a good way to document refactoring/API changes without forgetting stuff on the way, like "oh, but I forgot to note this change in the docs!".

That happens ALL the time, and just stopping a PR from being merged because of "missing docs" is much easier than running behind people and asking them to please do a PR on another repo too.
Reply | Threaded
Open this post in threaded view
|

AW: [zf-contributors] Merging documentation in the main repository

Marc Tempelmeier

+20 on this one!

 

Von: Marco Pivetta [mailto:[hidden email]]
Gesendet: Donnerstag, 20. Juni 2013 13:43
An: Eric Boh
Cc: Zend Framework Contributors
Betreff: Re: [zf-contributors] Merging documentation in the main repository

 

 

On 20 June 2013 13:38, Eric Boh <[hidden email]> wrote:

Why is it not sufficient enough to reference from or to a documentation PR? 

 

@coss that requires a lot of cross-checking work.

One Merge to rule them all, One Merge to find them,One Merge to bring them all and in the darkness bind them

Really, it's a good way to document refactoring/API changes without forgetting stuff on the way, like "oh, but I forgot to note this change in the docs!".

That happens ALL the time, and just stopping a PR from being merged because of "missing docs" is much easier than running behind people and asking them to please do a PR on another repo too.

Reply | Threaded
Open this post in threaded view
|

Re: Merging documentation in the main repository

Marco Pivetta
For those still wondering, this does not mean that docs will be distributed in your vendor dir.

If you run `composer update --prefer-dist` you will only get the source for the repo, so if anyone comes up with  "but it makes the repository too big" I don't think that's a valid argument.

The only problem I may see is the speed of travis builds (shouldn't be affected that much) and the subtree split that matthew does at every release...
Reply | Threaded
Open this post in threaded view
|

Re: Merging documentation in the main repository

bakura
This post has NOT been accepted by the mailing list yet.
In reply to this post by Marco Pivetta
I agree with that.

I also want to get rid of the strange format, and stick to plain markdown file with GitHub code extension (```php) for code. Really, the strange syntax and lack of tools for me just prevent me for writing more docs.

----------------------------------------
Michaël Gallego

Tel. : 06-98-82-62-38





Le 20 juin 2013 à 13:53, Marco Pivetta [via Zend Framework Community] <[hidden email]> a écrit :


On 20 June 2013 13:38, Eric Boh <<a href="x-msg://883/user/SendEmail.jtp?type=node&amp;node=4660392&amp;i=0" target="_top" rel="nofollow" link="external">[hidden email]> wrote:
Why is it not sufficient enough to reference from or to a documentation PR? 

@coss that requires a lot of cross-checking work.

One Merge to rule them all, One Merge to find them,One Merge to bring them all and in the darkness bind them

Really, it's a good way to document refactoring/API changes without forgetting stuff on the way, like "oh, but I forgot to note this change in the docs!".

That happens ALL the time, and just stopping a PR from being merged because of "missing docs" is much easier than running behind people and asking them to please do a PR on another repo too.



If you reply to this email, your message will be added to the discussion below:
http://zend-framework-community.634137.n4.nabble.com/Merging-documentation-in-the-main-repository-tp4660380p4660392.html
To start a new topic under ZF Contributor, email [hidden email]
To unsubscribe from ZF Contributor, click here.
NAML

Reply | Threaded
Open this post in threaded view
|

Re: Merging documentation in the main repository

robertboloc
In reply to this post by Marco Pivetta
I think it's a good idea! +1


2013/6/20 Marco Pivetta <[hidden email]>
For those still wondering, this does not mean that docs will be distributed in your vendor dir.

If you run `composer update --prefer-dist` you will only get the source for the repo, so if anyone comes up with  "but it makes the repository too big" I don't think that's a valid argument.

The only problem I may see is the speed of travis builds (shouldn't be affected that much) and the subtree split that matthew does at every release...

Reply | Threaded
Open this post in threaded view
|

Re: Merging documentation in the main repository

celinsmith111
This post has NOT been accepted by the mailing list yet.
In reply to this post by Marco Pivetta
Your idea is too great, merging documentation in respository is quite complex, many user reply it good.
celin is Zend Developer working for Zend Development Company.
Reply | Threaded
Open this post in threaded view
|

Re: Merging documentation in the main repository

Diego Sapriza
In reply to this post by robertboloc
its a +1 for me


On Thu, Jun 20, 2013 at 9:25 AM, Robert Boloc <[hidden email]> wrote:
I think it's a good idea! +1


2013/6/20 Marco Pivetta <[hidden email]>
For those still wondering, this does not mean that docs will be distributed in your vendor dir.

If you run `composer update --prefer-dist` you will only get the source for the repo, so if anyone comes up with  "but it makes the repository too big" I don't think that's a valid argument.

The only problem I may see is the speed of travis builds (shouldn't be affected that much) and the subtree split that matthew does at every release...




--

Diego Sapriza
Senior Software Engineer

case | 401 Broadway | Suite 1600 | New York NY 10013
Cell +598 94 317 737 | Office +598 2908 6408 | www.case-inc.com


Reply | Threaded
Open this post in threaded view
|

Re: Merging documentation in the main repository

richard
gh-pages branch for documentation with jekyll @ http://zendframework.github.io/zf2 ?


On Thu, Jun 20, 2013 at 2:09 PM, Diego Sapriza <[hidden email]> wrote:
its a +1 for me


On Thu, Jun 20, 2013 at 9:25 AM, Robert Boloc <[hidden email]> wrote:
I think it's a good idea! +1


2013/6/20 Marco Pivetta <[hidden email]>
For those still wondering, this does not mean that docs will be distributed in your vendor dir.

If you run `composer update --prefer-dist` you will only get the source for the repo, so if anyone comes up with  "but it makes the repository too big" I don't think that's a valid argument.

The only problem I may see is the speed of travis builds (shouldn't be affected that much) and the subtree split that matthew does at every release...




--

Diego Sapriza
Senior Software Engineer

case | 401 Broadway | Suite 1600 | New York NY 10013
Cell <a href="tel:%2B598%2094%20317%20737" value="+59894317737" target="_blank">+598 94 317 737 | Office +598 2908 6408 | www.case-inc.com



Reply | Threaded
Open this post in threaded view
|

Re: Merging documentation in the main repository

Marco Pivetta
No need for that - we have RTD for that, which works really well: http://zf2.readthedocs.org/

And that allows you to even compile your own PDF version of the entire manual



On 20 June 2013 16:01, Richard Jennings <[hidden email]> wrote:
gh-pages branch for documentation with jekyll @ http://zendframework.github.io/zf2 ?


On Thu, Jun 20, 2013 at 2:09 PM, Diego Sapriza <[hidden email]> wrote:
its a +1 for me


On Thu, Jun 20, 2013 at 9:25 AM, Robert Boloc <[hidden email]> wrote:
I think it's a good idea! +1


2013/6/20 Marco Pivetta <[hidden email]>
For those still wondering, this does not mean that docs will be distributed in your vendor dir.

If you run `composer update --prefer-dist` you will only get the source for the repo, so if anyone comes up with  "but it makes the repository too big" I don't think that's a valid argument.

The only problem I may see is the speed of travis builds (shouldn't be affected that much) and the subtree split that matthew does at every release...




--

Diego Sapriza
Senior Software Engineer

case | 401 Broadway | Suite 1600 | New York NY 10013
Cell <a href="tel:%2B598%2094%20317%20737" value="+59894317737" target="_blank">+598 94 317 737 | Office +598 2908 6408 | www.case-inc.com




Reply | Threaded
Open this post in threaded view
|

Re: Merging documentation in the main repository

localheinz
In reply to this post by Marco Pivetta
Hello Marco,


great idea!


Best regards,

Andreas
Reply | Threaded
Open this post in threaded view
|

Re: Merging documentation in the main repository

samsonasik
This post has NOT been accepted by the mailing list yet.
In reply to this post by Marco Pivetta
good idea. +1