ignite-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Branko ─îibej <br...@apache.org>
Subject Re: New home for Ignite documentation
Date Wed, 11 Mar 2015 05:20:01 GMT
On 08.03.2015 08:37, Dmitriy Setrakyan wrote:
> I agree about most points, and we are addressing them.
>
> I still want to say however, that there is nothing proprietary about
> keeping documentation hosted on readme.io. Apache Ignite is a fairly
> feature rich project, and we had to pick a tool that would not only produce
> documentation for us, but would also allow us to quickly add the
> documentation, quickly review it and publish it. Simply keeping MD files in
> the source tree requires lengthy customizations to CSS as well as writing
> documentation in a human unreadable format. Readme.io actually agreed to
> give us free hosing and allowed us to use their cool software for free. It
> would be a huge loss of productivity for us to abandon it.

Let me see if I understand this: readme.io is the only place where you
can edit the documentation. You cannot, currently, edit the markdown
with a text editor, commit it, then upload it to readme.io. In other
words, the repository is not the source of the documentation.

> Having said that, I have added the following:
> - Apache License: http://apacheignite.readme.io/v1.0/docs/license
> - ASF Copyright: http://apacheignite.readme.io/v1.0/docs/copyright
>
> I have also exported the documentation to our GIT source tree:
> https://git-wip-us.apache.org/repos/asf?p=incubator-ignite.git;a=tree;f=wiki;hb=refs/heads/sprint-2
>
> All committers have account in readme.io.

I don't. And I find no documented procedure on the Ignite web site or
elsewhere that would remind people to give new committers access to
readme.io.

>  On top of that, everyone in the
> community has a chance to suggest edits to any piece of the documentation
> via "Suggest Edits" link on every page (yet another cool feature provided
> by readme.io).
>
> However, I believe we have to live with creating documentation in readme.io
> first and then exporting it to GIT. I have also created a script which
> automatically goes through all MD files in the documentation and adds
> Apache License to it.

Can you write an automated script that proves that every change in the
documentation was made by an Ignite committer? Because that's what all
this boils down to: having a verifiable audit trail for every line of
source or documentation in a release. This is fundamental to the legal
requirements for a release. This is also the reason why the ASF insists
that repositories must be hosted on our infrastructure.

I believe that the scheme you set up with readme.io does not conform to
these requirements, but I'm not sure. We should ask on legal-discuss@. I
haven't come across an ASF project yet that doesn't generate
documentation from source in its repository; it feels wrong to me.

-- Brane

> On Thu, Mar 5, 2015 at 3:31 PM, Henry Saputra <henry.saputra@gmail.com>
> wrote:
>
>> The key is that the changes have to happen in the Apache Git before
>> copied to other location.
>>
>> Please do send the access information for Ignite readme.io to private@
>> list to make sure all committers have access.
>>
>> - Henry
>>
>> On Wed, Mar 4, 2015 at 2:18 PM, Dmitriy Setrakyan <dsetrakyan@apache.org>
>> wrote:
>>> readme.io is a very cool documentation platform which gives free web
>>> hosting, versioning, and sexy looks to open source projects, including
>>> Apache projects. It stores documentation in a regular markdown format,
>> and
>>> I will add the MD files to the GIT tree before doing the next release.
>> This
>>> way readme.io will be the copy of the documentation stored in github. I
>>> think we are compliant with Apache policies here.
>>>
>>> All Ignite committers have access to update the documentation. On top of
>>> that, the community can make suggestions to update any of the pages
>> through
>>> a very cool "Suggest Edits" feature in readme.io.
>>>
>>> Let me know if you have more questions.
>>>
>>> D.
>>>
>>>
>>> On Wed, Mar 4, 2015 at 1:43 PM, Henry Saputra <henry.saputra@gmail.com>
>>> wrote:
>>>
>>>> I am not sure how readme.io works but technically the actual content
>>>> should be hosted in apache domain.
>>>>
>>>> This is similar to our github repo which is merely mirror to Apache git
>>>> repo.
>>>>
>>>> The question is who has access to update readme.io for ignite and it
>>>> must be just mirror or copy from document content hosted somewhere
>>>> under Apache domain.
>>>>
>>>> On Sun, Feb 8, 2015 at 10:25 PM, Dmitriy Setrakyan
>>>> <dsetrakyan@apache.org> wrote:
>>>>> Hello Igniters,
>>>>>
>>>>> I think I have found a pretty cool home for our documentation:
>>>>> http://apacheignite.readme.io/v1.0/docs
>>>>>
>>>>> https://readme.io is nice enough to host open source documentation
>> for
>>>>> free, and I like the editability and friendliness of their UI.
>>>>>
>>>>> I have added most of the committers as admins to the documentation
>> wiki.
>>>>> Feel free to start contributing pages.
>>>>>
>>>>> D.


Mime
View raw message