CentOS docs - Sep 2015 - How GSoC project can fit in to CentOS Docs

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

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 ?

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)

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 :-)

- -- 

Fabian Arrotin
The CentOS Project | http://www.centos.org
gpg key: 56BEC54E | twitter: @arrfab
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.22 (GNU/Linux)

iEYEARECAAYFAlW/xmUACgkQnVkHo1a+xU6ylQCgml2UgH9Q9DuRczbdZNqedudw
yTQAn0NvZtyfNgCyhnvE/OifBXC62CLw
=vV7K
-----END PGP SIGNATURE-----

Fabian did you had chance to look at the working toolchain? We have
discussion going on here
http://lists.centos.org/pipermail/centos-docs/2015-August/005723.html

On Tue, Aug 4, 2015 at 1:22 AM, Fabian Arrotin <arrfab at centos.org>
wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> 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 ?
>
Building and displaying is the last part of the project. Until yesterday,
there was no mention of MoinMoin syntax, so right now we are building and
deploying directly to a website. But this can be controlled. This is the
very reason we wanted active community support from starting, but that
didn't happen.

>
> 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)
>
There was a length discussion regarding this on the list before. This is a
sort of conflicting interests thing. We want a new toolchain, but we don't
want to increase the overhead. We can move to Github only, but the initial
concern of Karsten was removing dependency on Github, providing an
alternate medium. Pagure is the lightest alternative to Github we can find.
It is light, and we will be hosting just docs repositories on it.

In future, if we SIG want their own docs repository , like Docker does, we
can move all the repositories of docs to this toolchain, since it provides
an alternative and better medium to contribute. Given this, the slight
overhead in infra of Pagure shouldn't be much problem, I guess.

>
> 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 :-)
>
>
Discussed on the mail about the project.
http://lists.centos.org/pipermail/centos-docs/2015-August/005723.html

> - --
>
> Fabian Arrotin
> The CentOS Project | http://www.centos.org
> gpg key: 56BEC54E | twitter: @arrfab
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v2.0.22 (GNU/Linux)
>
> iEYEARECAAYFAlW/xmUACgkQnVkHo1a+xU6ylQCgml2UgH9Q9DuRczbdZNqedudw
> yTQAn0NvZtyfNgCyhnvE/OifBXC62CLw
> =vV7K
> -----END PGP SIGNATURE-----
> _______________________________________________
> CentOS-docs mailing list
> CentOS-docs at centos.org
> http://lists.centos.org/mailman/listinfo/centos-docs
>


-- 
Regards,
Kunaal Jain
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.centos.org/pipermail/centos-docs/attachments/20150808/af32eef4/attachment-0002.html>

-----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-----

On 08/20/2015 02:57 AM, Karsten Wade wrote:
> -----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:
>> 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.
Did this documentation get written?  Can I get the repo for the source 
that drives the toolchain/workflow?

regards,

bex