CentOS docs - Aug 2015 - Working Documentation Toolchain [GSoC]

Hi,

The basic toolchain is up and running. I encourage community to test
this workflow once. It is an addition to the existing contributing
mediums.

Site: http://clown-olga-13325.bitballoon.com/
Contributing Docs repo : https://github.com/kunaaljain/test-centos-docs

==AIM=
Initial Idea : http://wiki.centos.org/GSoC/2015/Ideas#docs-toolchain

The CentOS Project needs more short-form contributions of content that
focuses on how-to do things on top of a CentOS Linux installation,
with a method to push changes in to appropriate and related upstream
open source projects.

There is a lot of content scattered across the Internet on how to do
things with CentOS Linux. The goal of this toolchain is to make it
easy for people to contribute new, short-form content articles to the
Project with an ability to push them outward to relevant upstream
projects.

==Workflow=
1. The user authors content in markdown format and creates a pull
request on Github.
2. The backend service mirrors the pull request to pagure and creates a issue.
3. The doc is built and a link is provided to preview the doc.
5. Staff reviews the docs, gives comments either on pagure or github
(two way synced)
4. Once the staff approves the doc is built and doc site updated.

==Infra=
1. A backend server listing to Github and Pagure webhooks and mirroring content.
2. A http site displaying the temporary docs.
3. A pagure instance

==Testing =
1. Fork the https://github.com/kunaaljain/test-centos-docs
2. Add new content to docs folder in mardown language.
3. Update the mkdocs.yml file and add the new file you just created
with appropriate heading.
4. Create a pull request.
5. Within 15-20 seconds, a comment will be made on pull request, with
the pagure link, which displaying various metadata.
6. Once the staff approves, PR is merged and site updated at
http://clown-olga-13325.bitballoon.com/

-- 
Regards,
Kunaal Jain

On 4 August 2015 at 14:21, kunaal jain <kunaalus at gmail.com>
wrote:
> Hi,
>
> The basic toolchain is up and running. I encourage community to test
> this workflow once. It is an addition to the existing contributing
> mediums.
>
> Site: http://clown-olga-13325.bitballoon.com/
> Contributing Docs repo : https://github.com/kunaaljain/test-centos-docs
>
> ==AIM=>
> Initial Idea : http://wiki.centos.org/GSoC/2015/Ideas#docs-toolchain
>
> The CentOS Project needs more short-form contributions of content that
> focuses on how-to do things on top of a CentOS Linux installation,
> with a method to push changes in to appropriate and related upstream
> open source projects.
>
> There is a lot of content scattered across the Internet on how to do
> things with CentOS Linux. The goal of this toolchain is to make it
> easy for people to contribute new, short-form content articles to the
> Project with an ability to push them outward to relevant upstream
> projects.
>
> ==Workflow=>
> 1. The user authors content in markdown format and creates a pull
> request on Github.
> 2. The backend service mirrors the pull request to pagure and creates a
issue.
> 3. The doc is built and a link is provided to preview the doc.
> 5. Staff reviews the docs, gives comments either on pagure or github
> (two way synced)
> 4. Once the staff approves the doc is built and doc site updated.
>
> ==Infra=>
> 1. A backend server listing to Github and Pagure webhooks and mirroring
content.
> 2. A http site displaying the temporary docs.
> 3. A pagure instance
>
> ==Testing =>
> 1. Fork the https://github.com/kunaaljain/test-centos-docs
> 2. Add new content to docs folder in mardown language.
> 3. Update the mkdocs.yml file and add the new file you just created
> with appropriate heading.
> 4. Create a pull request.
> 5. Within 15-20 seconds, a comment will be made on pull request, with
> the pagure link, which displaying various metadata.
> 6. Once the staff approves, PR is merged and site updated at
> http://clown-olga-13325.bitballoon.com/
Nice, from a very quick test it looks like this works well. I
submitted two changes.
One to update the MkDocs config and the other to add a testing page.

Is there a way for me to see the built version of docs for a pull request? The
build could be successful but something could be wrong with the formatting and
we wouldn't know.

You may want to use a Markdown linting tool, such as markdownlint. It can
easily be included in a Travis test run. We have started to use this
with MkDocs.
It allows you to help keep the Markdown consistent and it will also flag up some
common errors.

It looks like I managed to break the integration with this PR.
Presumably because
I branched from another PR that already had an issue on pagure?
https://github.com/kunaaljain/test-centos-docs/pull/19

Exciting to see this come together, and as always, please do bug me with any
MkDocs questions - I would be very happy to try and resolve any issues.

Dougal

On 4 August 2015 at 14:21, kunaal jain <kunaalus at gmail.com>
wrote:
> Hi,
>
> The basic toolchain is up and running. I encourage community to test
> this workflow once. It is an addition to the existing contributing
> mediums.
>
> Site: http://clown-olga-13325.bitballoon.com/
> Contributing Docs repo : https://github.com/kunaaljain/test-centos-docs
>
> ==AIM=>
> Initial Idea : http://wiki.centos.org/GSoC/2015/Ideas#docs-toolchain
>
> The CentOS Project needs more short-form contributions of content that
> focuses on how-to do things on top of a CentOS Linux installation,
> with a method to push changes in to appropriate and related upstream
> open source projects.
>
> There is a lot of content scattered across the Internet on how to do
> things with CentOS Linux. The goal of this toolchain is to make it
> easy for people to contribute new, short-form content articles to the
> Project with an ability to push them outward to relevant upstream
> projects.
>
> ==Workflow=>
> 1. The user authors content in markdown format and creates a pull
> request on Github.
> 2. The backend service mirrors the pull request to pagure and creates a
issue.
> 3. The doc is built and a link is provided to preview the doc.
> 5. Staff reviews the docs, gives comments either on pagure or github
> (two way synced)
> 4. Once the staff approves the doc is built and doc site updated.
>
> ==Infra=>
> 1. A backend server listing to Github and Pagure webhooks and mirroring
content.
> 2. A http site displaying the temporary docs.
> 3. A pagure instance
>
> ==Testing =>
> 1. Fork the https://github.com/kunaaljain/test-centos-docs
> 2. Add new content to docs folder in mardown language.
> 3. Update the mkdocs.yml file and add the new file you just created
> with appropriate heading.
> 4. Create a pull request.
> 5. Within 15-20 seconds, a comment will be made on pull request, with
> the pagure link, which displaying various metadata.
> 6. Once the staff approves, PR is merged and site updated at
> http://clown-olga-13325.bitballoon.com/

I don't have an account on Pagure, did it create one for me? How would I
then
access it? Looking at this:

https://pagure.io/user/d0ugal

Hi Dougal,

Thank you very much for testing and helping us find bugs!

About the account created on Pagure, it is created by the tool. Pagure uses this
mechanism that if a user is not registered yet, it will create the account using
the username, the full name and the email address, but without a password. So if
you would like to access the account, you may need to go through a ?lost
password? procedure. And in this case of pagure.io, as it uses Fedora Account
System (FAS), you may need to create a corresponding FAS account here
(https://admin.fedoraproject.org/accounts/user/new)

Also, a quick update about the bug you are experiencing, I checked the server
log and found that the program encountered no error. Also, as your account on
Pagure has been successfully created, I guess that pagure.io has accepted the
API call but somehow didn?t created the issue. I will post new update about this
bug here :)


Best regards,
Lei
> ? 2015?8?4????10:36?Dougal Matthews <dougal at dougalmatthews.com>
???
> 
> 
> I don't have an account on Pagure, did it create one for me? How would
I then
> access it? Looking at this:
> 
> https://pagure.io/user/d0ugal <https://pagure.io/user/d0ugal>
> _______________________________________________
> CentOS-docs mailing list
> CentOS-docs at centos.org <mailto:CentOS-docs at centos.org>
> http://lists.centos.org/mailman/listinfo/centos-docs
<http://lists.centos.org/mailman/listinfo/centos-docs>
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.centos.org/pipermail/centos-docs/attachments/20150805/abc56296/attachment-0002.html>

Hi,

An update about the bug. The bug was due to our method to create new issue on
Pagure. When creating a new issue using a new account, the program may encounter
some problems. Now we have fixed the bug :)

Thank you very much for helping us find it!


Regards,
Lei
> ? 2015?8?4????10:36?Dougal Matthews <dougal at dougalmatthews.com>
???
> 
> On 4 August 2015 at 14:21, kunaal jain <kunaalus at gmail.com
<mailto:kunaalus at gmail.com>> wrote:
>> Hi,
>> 
>> The basic toolchain is up and running. I encourage community to test
>> this workflow once. It is an addition to the existing contributing
>> mediums.
>> 
>> Site: http://clown-olga-13325.bitballoon.com/
>> Contributing Docs repo : https://github.com/kunaaljain/test-centos-docs
>> 
>> ==AIM=>> 
>> Initial Idea : http://wiki.centos.org/GSoC/2015/Ideas#docs-toolchain
>> 
>> The CentOS Project needs more short-form contributions of content that
>> focuses on how-to do things on top of a CentOS Linux installation,
>> with a method to push changes in to appropriate and related upstream
>> open source projects.
>> 
>> There is a lot of content scattered across the Internet on how to do
>> things with CentOS Linux. The goal of this toolchain is to make it
>> easy for people to contribute new, short-form content articles to the
>> Project with an ability to push them outward to relevant upstream
>> projects.
>> 
>> ==Workflow=>> 
>> 1. The user authors content in markdown format and creates a pull
>> request on Github.
>> 2. The backend service mirrors the pull request to pagure and creates a
issue.
>> 3. The doc is built and a link is provided to preview the doc.
>> 5. Staff reviews the docs, gives comments either on pagure or github
>> (two way synced)
>> 4. Once the staff approves the doc is built and doc site updated.
>> 
>> ==Infra=>> 
>> 1. A backend server listing to Github and Pagure webhooks and mirroring
content.
>> 2. A http site displaying the temporary docs.
>> 3. A pagure instance
>> 
>> ==Testing =>> 
>> 1. Fork the https://github.com/kunaaljain/test-centos-docs
>> 2. Add new content to docs folder in mardown language.
>> 3. Update the mkdocs.yml file and add the new file you just created
>> with appropriate heading.
>> 4. Create a pull request.
>> 5. Within 15-20 seconds, a comment will be made on pull request, with
>> the pagure link, which displaying various metadata.
>> 6. Once the staff approves, PR is merged and site updated at
>> http://clown-olga-13325.bitballoon.com/
> 
> 
> I don't have an account on Pagure, did it create one for me? How would
I then
> access it? Looking at this:
> 
> https://pagure.io/user/d0ugal <https://pagure.io/user/d0ugal>
> _______________________________________________
> CentOS-docs mailing list
> CentOS-docs at centos.org <mailto:CentOS-docs at centos.org>
> http://lists.centos.org/mailman/listinfo/centos-docs
<http://lists.centos.org/mailman/listinfo/centos-docs>
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.centos.org/pipermail/centos-docs/attachments/20150805/3026129f/attachment-0002.html>