Re: [incubation] Policy: Access rights to GitHub Wiki

[Mickael Istria <mistria@xxxxxxxxxx>]

On Mon, Jul 10, 2017 at 12:27 PM, Oliver Kopp <kopp.dev@xxxxxxxxx> wrote:

In case, however, a contributor wants to add text to github-pages, the IP process has to be kicked off: The documentation relies inside the "doc" folder of the source code repository. This causes load on the EMO IP team, which I'd like to reduce and not to increase.

Maybe it would be interesting to rise the question to IP team about whether documentation is to be perceived as code and is subject to IP rules. And maybe it's also worth changing the rules.

 

Thus, I decided for using the GitHub wiki page (i.e., https://github.com/eclipse/winery/wiki in the context of winery). See also https://dev.eclipse.org/ipzilla/show_bug.cgi?id=13783
I accept that the Wiki is not rendered that nicely (point ii), that the documentation is not at the same place as the code (point iii) and that I cannot use GitHub's pull request review system (point iv).

Since contributors are not allowed to edit the Wiki directly, the approach to get content in is via "git magic": The contributor clones the wiki locally, does the edits and pushes the changes to a git repository X. I fetch from X, review the changes and push the changes to the Eclipse.

Is this workflow intended? Acceptable? What do other projects do for their documentation. What is best practice?

I think all those are more important concerns for your project than the load on the IP team. You should focus on making your project successful more than anything else. So maybe you should abandon the wiki for those reason and find something that works both for your project and IP team.

Also, as the wiki is part of the repo (I believe), your workaround may still be subjet to IP review.

I personally strongly prefer having doc in the same repo as code to better keep things sync'd and to have homogeneous workflows for all kind of contributions (those are the multiple points you've mentioned).

Please discuss that directly with IP team and try to find a compromise about documentation. And maybe this is something the EMO&Board should clarify or change.

That's definitely an interesting issue you have, and I believe finding the best solution is something that will be very protifable for the whole community!

 

When seeing https://eclipse.org/che/, I think, I should generate a GitHub repository "winery-homepage", which uses Jekyll to generate the HTML files and then "push" the generated HTMLs to the Eclipse infrastructure. So, I could take the advantages of (i), (ii) and (iv).

Such another GitHub repository, if you want it to be under the Eclipse.org umbrella, would have the same IP rules as your main repo, so I don't think it would help.

--

Mickael Istria

Eclipse IDE developer, at Red Hat Developers community