Hi, Thank you very much for the detailed suggestions! > 在 2015年6月5日，下午11:19，Sankarshan Mukhopadhyay <sankarshan.mukhopadhyay at gmail.com> 写道： > > On Fri, Jun 5, 2015 at 7:55 PM, Lei Yang <yltt1234512 at gmail.com> wrote: >> Our GSoC project is not very similar with a conventional doc toolchain. Its >> goal is to lower the barrier for new comers to contributor. Especially for >> those short-form how-to docs. Here is the original idea >> (http://wiki.centos.org/GSoC/2015/Ideas#docs-toolchain) for your reference. > > Thanks for the link to the project concept. From the point-of-view of > a peripheral participant in the upstream documentation communities of > Fedora, OpenStack and Gluster my take on 'lowering the barrier' is > around creating a system where a casual contributor can write, commit > and publish content that is automatically rendered on to the live > site. Exactly. > > Of course, this description tends to abstract the concept of a > community of reviewers, workflow tooling and actual governance (eg. > who can sign off on patches/contribs etc). But it does provide enough > sweeping generalities to begin to look at things. > >> Taking that into consideration, we think that we should make use of github >> as that’a a platform that almost all potential contributors are familiar >> with. We don’t want to involve many command line executions. So we suppose >> that users make PR on github. However, at the same time, we don’t want to >> fully rely on a third party service like github, so we choose to store the >> original git repo on git.c.o. Pull requests happen on github, and changes >> are synced back to git.c.o after reviewing. Finally the doc is built based >> on git.c.o. That’s the workflow. > > A number of upstream projects are choosing AsciiDoc/Markdown and > github for various obvious reasons. One of which being making it easy > for contributors to use lightweight editors (eg. <https://atom.io/>) > or, familiar daily ones (eg. vi/emacs) to write the content without > minimal requirements to learn a lot of tags/semantics. > > The workflow you mention is logically sound. Although I cannot fathom > where usage of a bugzilla instance fits in. You are probably using > github.com as the back-up/archival repo with g.c.o being the primary > one. That's somewhat odd, but I don't have anything against that plan. In our plan, the changes are made first on github and then synced back to git.c.o. After a commit is merged on github, we sync the changes back to git.c.o. And new updates is built into doc based on git.c.o. And about bugzilla, we plan to build a place where staff can review, comment about and choose to merge the commits. And we don’t want to rely too much on github, so we don’t just use github’s issue tracking system. This is how we plan to use bugzilla (or other similar platforms): When a new PR appears on github, the toolchain creates a corresponding "bug report” on bugzilla. So the staff have a place to discuss about the new contribution. We think that some contributors might are only familiar with github, so we keep everything synced between github and bugzilla, so the contributor can use either platform to discuss with the staff. Actually we first chose bugzilla because we discovered that it provides most kinds of APIs. I am sorry that our research was not very sufficient and didn’t realize that we can use the existing bugs.centos.org <http://bugs.centos.org/> (Mantis). Thank you very much for your advice! > >> To implement this, we need to integrate github and git.c.o. One of the steps >> is to provide a place where staff can review the changes and choose to >> accept the contribution. First we planed to use bugzilla, but in the >> discussion with Karsten and in the discussion on this list, we learned that >> using bugzilla will add extra burden to maintain it, so we might switch to >> bugs.centos.org. Using which platform is still to be discussed, and we may >> have a meeting on #centos-devel. > > And this is where I am still puzzled. Bugzilla is a defect > tracking/ticketing tool. It really doesn't lend itself to be a patch > review tooling. Why would you be interested in modifying or,writing > plugins for Bugzilla to do this? Are there no other tools/systems > which can get this review component done? Yes, as I mentioned above, we compared many bug tracking systems and code reviewing systems. We chose bugzilla because its APIs seem to be well documented and clear to use. We didn’t dig much into other features. Now that we can use bugs.centos.org <http://bugs.centos.org/>, we are now researching Mantis and might integrate mantis with github. > >> Our project is aimed at short-form how-to docs and lowering the barrier, so >> conventional workflows might not work well in our project. > > While your project might be enabling short-form docs you'll have to > consider that it should make it easy to maintain the state of content. > Stale or, out-of-sync content is a bigger problem than no content. And > it is possible that you lay down a framework that is adopted across > CentOS for all documentation. > Thank you for your remind. We haven’t considered very much about keeping the content updated. Maybe we keep track of all the docs’ creation date and corresponding CentOS version number, and notice the staff when a doc is out of date. Do you have some suggestions about this? Regards, Lei > > -- > sankarshan mukhopadhyay > <https://about.me/sankarshan.mukhopadhyay> > _______________________________________________ > CentOS-devel mailing list > CentOS-devel at centos.org > http://lists.centos.org/mailman/listinfo/centos-devel -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.centos.org/pipermail/centos-devel/attachments/20150606/2c3e799e/attachment-0008.html>