[jira] [Commented] (MESOS-744) Possibly move /docs/ folder out of Mesos core, into separate repo

["Vinod Kone (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/MESOS-744?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13796452#comment-13796452 ] 

Vinod Kone commented on MESOS-744:
----------------------------------

I am not sure moving docs out of the repo is the right solution. Here are my reasons

--> git submodules are horrible. we researched using them for libprocess/stout and backed away because of how its designed.

--> i think it doesn't matter for users whether the docs exist in mesos repo or separate repo when it comes to contribution. they can easily send pull requests via github.

--> tagging docs with releases is going to be harder as you mentioned.

I think what we need is tooling for generating reviewboard reviews from github pull requests. [~chrismattmann] mentioned such tooling exists at apache. we should get that setup.

> Possibly move /docs/ folder out of Mesos core, into separate repo
> -----------------------------------------------------------------
>
>                 Key: MESOS-744
>                 URL: https://issues.apache.org/jira/browse/MESOS-744
>             Project: Mesos
>          Issue Type: Documentation
>            Reporter: Dave Lester
>            Assignee: Dave Lester
>            Priority: Minor
>
> I'd like to propose moving the /docs/ folder out of the Mesos core, and into a separate repo on github. This is a good idea for a few reasons, including:
> 1) We could easily share the repo between Mesos git repository (/docs/ would included as a submodule), as well imported into the Mesos website. Currently, docs files are not used in the Mesos website, so we have to send users to github to view rendered markdown. Breaking it into a separate repo would would make it simple for us to render the docs at mesos.apache.org
> 2) It would be significantly easier for community members to contribute. A simple pull request could make minor changes. In fact, a number of these changes have already been made to the documentation (https://github.com/apache/mesos/pulls), but we have no current way to process them. Right now our process requires the same level of complexity and creating unique Apache accounts if they want to make simple updates to the documentation.
> 3) It could provide an opportunity for community ownership of the docs, which at this point have tended to be an afterthought of core developers.
> The only main disadvantage that I see in this approach would be maintaining an additional repository and possible coordination in releases, however I see this as relatively minor. The specifics of how this affects tagging could be discussed further, I don't feel strongly about it.



--
This message was sent by Atlassian JIRA
(v6.1#6144)