Hi,
Over the last week, Lei and I have been researching about the review
platform where the content submitted can be reviewed, commented, tagged and
pushed. This will be an alternative to github pull requests interface, which
will thus reduce our dependency on Github in case Github changes its API
anytime in future.
Even firefox is considering using Github as an alternative medium to receive
contribution.
http://gregoryszorc.com/blog/2015/01/12/utilizing-github-for-firefox-development/
Lei made a great chart comparing the platforms.
https://drive.google.com/file/d/0B9sUy41_Rk3KdGl4RVhDSXZIZmc/view?usp=sharing
So overall Bugzilla looks a great option. But there is one major flaw, we
need to view the article submitted at each point(code review) which bugzilla
lacks.
The solution to this is creating a plugin for markdown previewing.
The typical workflow might look like this:
1. Author writes content in markdown language.
2. Makes a pull request on github.
3. Corresponding to the pull request a issue is created on bugzilla.
4. CentOS staff can either review the article on github pull request, or on
bugzilla.
5. Comments are two way synced.
6. 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.
8. Staff tags it, and pushes to git.centos.org.
9. Using git.centos.org, new website is generated and pushed.
There are many challenging tasks in this, especially the bugzilla issue
creation on pull request and two way comment sync. This has never been done
before, but we looked at the API and think we can make it work. Another
challenging task is markdown preview on bugzilla.
As a word of warning here, not all Markdown parsers and renderers arethe same. GitHub's makes a number of additions and changes that goagainst the original (admittedly vague) spec. This could mean yourpreviews are different and may not match the documentation build. Analternative approach would be to build the docs in CI and link to thebuilt version in a comment on both systems.
Thanks very much for your advice!
We are planning to use Bugzilla, which doesn’t have a built-in code preview function. So we will need to use an external place to provide article review. Building the article in a CI and attach the link on github and reviewing platform would be a great solution. And about markdown standard, it will be a problem to solve.
|
_______________________________________________
CentOS-docs mailing list
CentOS-docs@xxxxxxxxxx
http://lists.centos.org/mailman/listinfo/centos-docs
