[CentOS-docs] How GSoC project can fit in to CentOS Docs

Thu Aug 20 00:57:55 UTC 2015
Karsten Wade <kwade at redhat.com>

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 08/03/2015 12:52 PM, Fabian Arrotin wrote:
> On 03/08/15 18:23, kunaal jain wrote:
> 
>> Would start with the note that the basic project is complete. I 
>> would be releasing the prototype on a separate thread. But for
>> the discussion sake the workflow will look like this : Authors 
>> contribute content in markdown format, on github. The pull
>> request created gets mirrored to pagure thus saving dependency on
>> github. Also the PR content is built using CI to preview how it
>> looks. The PR is two way synced between the platforms, so that
>> individual can use pagure or github. Once staff approves the
>> post, website is built and deployed.
> 
> <snip>
> 
> So, trying to understand the goal : can you define what you mean
> by "website is built and deployed" ? Do you mean you produce
> MoinMoin compatible syntax and sorted by categories/hierarchy, to
> then be automatically synced to wiki.centos.org ? Or do you mean
> another (and so parallel) website ?

At the moment, it's a parallel website.

http://clown-olga-13325.bitballoon.com/

I agree that it made sense for the students to do a stand-alone
autobuild solution so they didn't have to dive in to dealing with wiki
as final destination. Publishing location /should/ be automated, but
may not be possible in all cases.

If we reach consensus that the Moin Moin wiki is the best publication
location for these short-form articles, we'll have to work through the
steps to get wiki markup and some way to easily
publish-with-editorial-controls.

> Wrt pagure, I admit I looked at it and found it cool, plus I know 
> Pierre-Yves (hey !). But wondering if adding 
> yet-another-git-server-plus-layer is the way to go in our infra,
> while all centos git repositories are hosted on a "gitblit powered"
> server (on git.centos.org)

Goal was not to add more Git layers of management, but to remove a
reliance on GitHub's closed-source task management layers, without
hassles of hooking in to Mantis (and not using Bugzilla.)

I agreed with going for the Pagure solution because the worst-case is
that we have to borrow Fedora's instance or host our own, and it's an
actively maintained tool for just this situation (getting a
GitHub-like issue tracking process for documentation with a FLOSS tool.)

I may be missing something here about simplicity, though -- we also
have the whole angle of building these docs with CI, so there are a
lot of "where does what pull from to do which to what" to consider.

> Is that possible to  have an overview of the infra and goals (aka
> the architecture) of this GSoC doc project ? that would help 
> understanding, as I agree that I'm currently lost, and I'm
> probably not the only one, also the reason for that thread :-)

I'd be totally happy to do this, what's the best medium? I could get
on a public Google Hangout with you, and then we could write up a
document from that?

There is a bit of infra that needs to be brought up and maintained --
that /should/ be written in to any documentation that Kunaal and Lei
have written, which is due by this week. Likely we'll need to take
their developer specs and convert them to operational specs.

The goal is to support a writing workflow that goes like this:

1. Author finds or writes appropriately licensed content.
   - Method works best for short-form (v. full manuals) content types.
2. Author is able to use Git-based tools to write and submit content.
3. Editors are able to use Git-based & FLOSS tools with notifications
to learn about documents in the edit-queue, read, and respond to
short-form articles.
4. At the end of this needs to be a way to i) pick up markup content
to publish, and/or ii) auto-publish once editor chooses to publish.

The specific details of how this is configured with the currently
coded solution is what Kunaal and Lei have been describing.

For 'Git-based writing tools' we have the ability to interact via
GitHub, using it's web-based text editing tools as well as remote
command line tooling with 'git'.

After a Pull Request is made to GitHub, an issues is opened in Pagure,
which acts as the task-tracking queue for editors.

Editors can then approve and, ideally, get pull in to git.centos.org
and automatically publish somewhere.

Where is somewhere?

What else is not explained enough above?

Let's dig in to those details to figure out the complexity and such
that is needed.

Regards,

- - Karsten
- -- 
Karsten 'quaid' Wade        .^\          CentOS Doer of Stuff
http://TheOpenSourceWay.org    \  http://community.redhat.com
@quaid (identi.ca/twitter/IRC)  \v'             gpg: AD0E0C41
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.22 (GNU/Linux)

iEYEARECAAYFAlXVJhMACgkQ2ZIOBq0ODEF71gCgk425gU+IZzIksq1v50uRh5Tn
/I8An3KBlNFfwb+niYfVXG+LGuvOeJEN
=Lxea
-----END PGP SIGNATURE-----