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 (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, 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@centos.org
http://lists.centos.org/mailman/listinfo/centos-devel