Lei Yang
2015-May-22 14:47 UTC
[CentOS-docs] IRC Log - Kunaal and Lei - New Doc Toolchain - 05/20/2015
Hi!
Kunaal and I had an IRC chat last Wednesday at UTC 0600. We discussed about the
new docs toolchain.
The first part of the chat log is about the workflow, here is the summary:
1. user write on local text editor / on github or a web based editor
2. the PR is created on github, and the info is synced to a reviewing platform,
where staff discussed about, tag and accept the file
3. if the PR is accepted, the new article is synced from github to
git.centos.org
4. new article is deployed and the doc site is updated
5. a tool convert the new article to different formats for upstream projects to
use
<kunaaljain> hey
<yangl1996> hi!
<kunaaljain> So did u think anything about project
<yangl1996> I think something about the timeline
<kunaaljain> tell me
<yangl1996> I think by midterm, we should generally finish
half of the reviewing platform and the syncing tool
<kunaaljain> Reviewing platform is definitely a big task
<yangl1996> yes
<yangl1996> we can ask on the mailing list for some existing
open source project
<kunaaljain> We have one and half month for the mid terms
<yangl1996> such as some bug tracking platform
<yangl1996> yes
<kunaaljain> let's see tools required according to workflow
<kunaaljain> First user writes a content
<kunaaljain> Where does he write it?
<yangl1996> I thought about three ways:
<yangl1996> 1. he writes on local computer and push it to
github
<yangl1996> 2. he write on a web-based editor
<yangl1996> 3. he write directly on github
<yangl1996> do you have other ideas?
<kunaaljain> Sounds good to me. Github uses its own github
markdown language
<kunaaljain> So we adapt that?
<yangl1996> oh it is a problem
<yangl1996> i have no idea currently
<yangl1996> although adapting it will make the language more
powerful,
<yangl1996> it is not "standard" markdown
<kunaaljain> We can use that. its almost standard i think
<yangl1996> sounds good to me
<kunaaljain> adapting this will help us using github tools
<yangl1996> good idea!
<kunaaljain> about web - based editor. New editor or existing
tools
<yangl1996> I think we can use existing tools, because
developing a new editor is a huge task in my mind - if we have time after
finishing other parts, we can build one
<kunaaljain> Yeah, if we have left over time, we will do that.
<yangl1996> good idea!
<kunaaljain> Okay so content is written
<kunaaljain> A pull request has been created on github
<kunaaljain> any other option?
<yangl1996> yes, totally agreed
<kunaaljain> then what happens next?
<yangl1996> now that the content is on github, the staff
should review it, tag it and comment on it
<kunaaljain> Yes but what happens internally?
<kunaaljain> Tool wise
<yangl1996> maybe the commit should trigger the syncing tool?
<kunaaljain> there is no commit yet. Just a Pull Request
<yangl1996> so the commit info is synced to reviewing platform
<yangl1996> the staff need to review it and comment on it
<kunaaljain> Maybe this pull request creates a issue in review
platform
<yangl1996> yes, exactly what I think
<kunaaljain> This review platform helps in tagging and
commenting?
<yangl1996> yes
<kunaaljain> Sounds good to me. Once the content is tagged and
commented.
<kunaaljain> Changes are made.
<yangl1996> yes, the staff accept the new content
<kunaaljain> Then there should be an option to commit and
close.
<kunaaljain> exactly
<yangl1996> and the pull request can be merged in the repo on
github
<kunaaljain> once the commit is made, this is synced to git.c.o
<yangl1996> yes
<yangl1996> there involves some communication with github
<kunaaljain> Yes one way sync?
<yangl1996> I think the communication happens in these
situations:
<yangl1996> 1. github sync commit info to reviewing platform
(create a issue on reviewing platfrom)
<yangl1996> 2. when staff accept the commit on reviewing
platfrom, this actions is synced to github
<yangl1996> 3. the one way sync of repo data from github to
git.c.o
<yangl1996> do you have some ideas?
<kunaaljain> Yes. Also the issue needs to be synced i think
<yangl1996> yes!
<kunaaljain> because staff comments and suggests changes
<yangl1996> exactly
<kunaaljain> new changes are made on that pull request on
github
<kunaaljain> these changes have to be reflected on our platform
<yangl1996> so this should be a two-way sync
<yangl1996> yes I agree with you
<kunaaljain> then 3rd point you made is correct
<kunaaljain> one way sync from github to git.c.o
<yangl1996> yes
<kunaaljain> once sync is done, Then new site has to be
generated and deployed.
<yangl1996> we can use open source tools to do this
<kunaaljain> Yes that sounds easy.
<yangl1996> Mkdocs
<yangl1996> we can use that
<kunaaljain> ;) Then upstream projects
<yangl1996> :) yes
<yangl1996> we use pull model
<kunaaljain> here a REST API?
<yangl1996> sounds good!
<kunaaljain> This will take some time I guess. Totally a new
model here
<kunaaljain> I don't think previously it has been
implemented
<yangl1996> yes, we need to build from bottom up
<yangl1996> I think so
<yangl1996> a have no idea about how open source projects
share docs
<yangl1996> do they use some special format / conventions?
<kunaaljain> I don't think there is such thing till now.
<kunaaljain> so we have the basic workflow defined now?
<yangl1996> i think so
<kunaaljain> so in basic tool chain
<kunaaljain> what else we need
<yangl1996> don't know whether we need other parts
<yangl1996> do you have some ideas?
<kunaaljain> I think what we discussed covers the basic part
<yangl1996> yes
<kunaaljain> Content writing -> reviewing -> deployment
-> upstream
<yangl1996> exactly what a doc system needs
<kunaaljain> Yes.
<yangl1996> here is the ether pad link:
http://etherpad.osuosl.org/CentOS-Docs-toolchain
<http://etherpad.osuosl.org/CentOS-Docs-toolchain>
<yangl1996> let's add the workflow to it
<kunaaljain> Now I think it is very difficult to divide the
proposed tools between us so that we can work independently
<yangl1996> so others can know our idea at once
<yangl1996> yes, so much dependency between parts
<kunaaljain> Yeah definitely
<kunaaljain> So What do you think? Working independently or
together?
<kunaaljain> Is it possible?
<yangl1996> if we will work in parallel, we need to define a
set of APIs
<yangl1996> mainly between syncing tool and reviewing platform
<kunaaljain> Defining before start is hard I think
<kunaaljain> especially when we don?t know
<yangl1996> I think so!
<kunaaljain> how reviewing platform will work
<yangl1996> yes exactly
<kunaaljain> Development of it from scratch is not possible
<yangl1996> yes
<yangl1996> i am searching for some open source bug tracking
platform
<kunaaljain> Yes. We can modify it but we need the base
<yangl1996> yes
<kunaaljain> So either we can work parallel and discuss
everyday what we are doing, We can share work and problems
<yangl1996> I totally agree
<yangl1996> we need to sync our progress frequently
<yangl1996> maybe this will be of some use:
http://en.wikipedia.org/wiki/Comparison_of_issue-tracking_systems
<http://en.wikipedia.org/wiki/Comparison_of_issue-tracking_systems>
<kunaaljain> The list is quite big. You have a look at them, I
will too
<yangl1996> ok!
<yangl1996> and I found centos is now using mantis as bug
tracker: http://www.mantisbt.org/demo.php
<http://www.mantisbt.org/demo.php> , I will see the features mantis
supports
<kunaaljain> centos doesnt use bugzilla?
<kunaaljain> note that mantis is not open source
<yangl1996> oh! that's bad
<yangl1996> we need to use open source tools
<kunaaljain> no no
<kunaaljain> it is open source
<kunaaljain> http://www.mantisbt.org/download.php
<http://www.mantisbt.org/download.php>
<kunaaljain> https://github.com/mantisbt/mantisbt
<https://github.com/mantisbt/mantisbt>
<yangl1996> yeah!
<yangl1996> about the reviewing platform
<yangl1996> how do we implement it
<kunaaljain> Ours requirement is not exactly as bug tracking
<kunaaljain> we need to interact with github at each point
<yangl1996> i agree with you
<yangl1996> what we build is a platform syncing data with
github realtime
<kunaaljain_> I think once
<kunaaljain_> we decide on review platform
<kunaaljain_> we can divide work and start
<kunaaljain_> but we need review platform details first i think
<yangl1996> yes
<yangl1996> let's discuss in in detail;
<kunaaljain_> yeah
<yangl1996> what can it do
<yangl1996> commenting, tagging
<yangl1996> just like github's issue tracking tool i think
<kunaaljain_> yes
<kunaaljain_> Exactly
<kunaaljain_> it is like bugzilla + github
<yangl1996> yes!
<kunaaljain_> so what we do for this?
<yangl1996> can we base the platform on bugzilla
<kunaaljain_> bugzilla meets our requirements?
<yangl1996> i think no
<yangl1996> we need to develop new features
<kunaaljain_> what about other platforms?
<kunaaljain_> the list you gave
<yangl1996> we need to integrate with git, so the choice
narrows down a bit
<kunaaljain_> so the first task is
<kunaaljain_> find a reviewing platform
<kunaaljain_> can we do this by today
<kunaaljain_> so that we can meet up tomorrow
<kunaaljain_> or day after tomorrow again
<kunaaljain_> discuss the API and changes in platform
<yangl1996> yes exactly
<kunaaljain_> and start working on it
<yangl1996> ok!
<kunaaljain_> Regarding dividing work
<kunaaljain_> One option is we work parallel as reviewing
platform definitely requries that we both work together
<yangl1996> yes
<kunaaljain_> so we can work together. the only con is we become
dependent. We won;t be able to quantify our individual effort. It will like a
team. I am okay with it I think
<yangl1996> I am okay, too
<kunaaljain_> Great! So let's hunt a review platform fast.
<kunaaljain_> Once we finalise that
<kunaaljain_> we will work on timeline
<kunaaljain_> and then finally start coding :D
<yangl1996> ok! I've narrowed down the choice from the
list to a few open source projects
<yangl1996> :D
<kunaaljain_> Great. Keep me informed about the same. I will too
look at them :)
<yangl1996> with requirement of supporting git and being open
source, there are three choices from the list: http://www.fusionforge.org
<http://www.fusionforge.org/> , http://www.redmine.org
<http://www.redmine.org/>, http://trac.edgewall.org
<http://trac.edgewall.org/>
<yangl1996> and bugzilla
<kunaaljain_> okay
<yangl1996> I am trying redming
<yangl1996> http://demo.redmine.org
<http://demo.redmine.org/>
<yangl1996> I registered an account so we can try the demo,
login: gsoc_test password: gsoc_test
<kunaaljain_> I will try it :)
<yangl1996> :D
----------------
Lei
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.centos.org/pipermail/centos-docs/attachments/20150522/e1763969/attachment-0002.html>
Possibly Parallel Threads
Wisdom of the Ancients
