On Tue, Mar 10, 2015 at 10:20 PM, Branko Čibej <[email protected]> wrote:
> 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. > You can, if you like, make edits in markdown document directly and then paste them into readme.io. > > > 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. > You do now (see my other email) > > > 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. > There is plenty of documentation in Apache TLPs which is being hosted in Atlasssian Confluence as well (https://cwiki.apache.org/). I assure you that in those cases Confluence is the primary editor of that documentation, and that it never ends up directly in the source tree. Can you explain why that process is any better than the one we have setup? Having said that, we still can setup a process which ensures that after any committer makes any changes in readme.io, they export them to GIT and commit them. This way the trail will be there. It is a soft contract, but nevertheless, committers can follow it. We community agrees, I will document this process, ironically, on readme.io :) Lastly, I think we should be viewing readme.io as a productivity tool, much the same as IDEA or Eclipse for java development. It's a pleasure to work with readme.io, and is a huge productivity boost compared to raw text editing. I would not try to fight it, but instead suggest any changes we have to make to the process (if any at all), so we can continue using it. > 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 <[email protected]> > > 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 < > [email protected]> > >> 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 <[email protected] > > > >>> 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 > >>>> <[email protected]> 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. > >
