On Sat, May 30, 2015 at 1:04 AM, kunaal jain <kunaalus at gmail.com http://lists.centos.org/mailman/listinfo/centos-devel> wrote:
The typical workflow might look like this:
- Author writes content in markdown language.
- Makes a pull request on github.
Is this github.com or, a git instance off CentOS infrastructure?
Authors are supposed to make a pull request on github.
- Corresponding to the pull request a issue is created on bugzilla.
- CentOS staff can either review the article on github pull request, or on
bugzilla.
I would recommend using one tool for handle inbound and review. Having 2 tools that need to be kept synchronized would add overhead that you don't want to deal with. Also, it has the effect of puzzling contributors.
Thanks for your suggestion!
Staff will do the review only on bugzilla, but we think some contributors are only familiar with github, so we sync the comments between two platforms, so contributors don’t need to leave github to finish the whole process.
- Comments are two way synced.
- At each point the article can be viewed on bugzilla, using an extension
we propose to make. 7. After many iterations of commenting, and improving, article is finally accepted.
Have you considered review workflow tools like Gerrit?
We considered Gerrit and other code review platforms. However we are handling markdown or some similar markup languages, so we plan to build the doc on a CI and let the staff review the built docs.
- Staff tags it, and pushes to git.centos.org.
- Using git.centos.org, new website is generated and pushed.
'Website' or, is the content rendered from the version control (g.c.o) and pushed live?
The content is rendered from g.c.o. built into HTML files using static site generator tool like jekyll.
Regards, Lei
On Fri, Jun 5, 2015 at 6:49 PM, Lei Yang yltt1234512@gmail.com wrote:
Staff will do the review only on bugzilla, but we think some contributors are only familiar with github, so we sync the comments between two platforms, so contributors don’t need to leave github to finish the whole process.
Allow me to change the context/track. Have you taken a look at https://wiki.openstack.org/wiki/Documentation/HowTo#Workflow ? Reading this conversation it would seem that your proposal aims to achieve similar goals even though you may not choose to opt for similar tools.
Hi,
Thank you for your suggestion!
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 http://wiki.centos.org/GSoC/2015/Ideas#docs-toolchain) for your reference.
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.
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 http://bugs.centos.org/. Using which platform is still to be discussed, and we may have a meeting on #centos-devel.
Our project is aimed at short-form how-to docs and lowering the barrier, so conventional workflows might not work well in our project.
Thanks again for your suggestion.
Regards, Lei
在 2015年6月5日，下午9:26，Sankarshan Mukhopadhyay sankarshan.mukhopadhyay@gmail.com 写道：
On Fri, Jun 5, 2015 at 6:49 PM, Lei Yang yltt1234512@gmail.com wrote:
Staff will do the review only on bugzilla, but we think some contributors are only familiar with github, so we sync the comments between two platforms, so contributors don’t need to leave github to finish the whole process.
Allow me to change the context/track. Have you taken a look at https://wiki.openstack.org/wiki/Documentation/HowTo#Workflow ? Reading this conversation it would seem that your proposal aims to achieve similar goals even though you may not choose to opt for similar tools.
-- sankarshan mukhopadhyay https://about.me/sankarshan.mukhopadhyay _______________________________________________ CentOS-devel mailing list CentOS-devel@centos.org http://lists.centos.org/mailman/listinfo/centos-devel
On Fri, Jun 5, 2015 at 7:55 PM, Lei Yang yltt1234512@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.
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.
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?
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.
Hi,
Thank you very much for the detailed suggestions!
在 2015年6月5日，下午11:19，Sankarshan Mukhopadhyay sankarshan.mukhopadhyay@gmail.com 写道：
On Fri, Jun 5, 2015 at 7:55 PM, Lei Yang yltt1234512@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@centos.org http://lists.centos.org/mailman/listinfo/centos-devel
-
Lei Yang -
Sankarshan Mukhopadhyay