Asciidoctor :: Discussion

Documenting asciidoctor modules releases

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

8 messages Options

abelsromero

Documenting asciidoctor modules releases

Hi all,

Many great things are going on and I feel like the need to document releases is getting more and more important everyday. The main problems I see are these:
1. It's hard to keep track of everything.
2. It's hard to elaborate a release document to be used on the blog or the site. This should include improvements as well as bug fixes. The later, imho, even more important.

With my limited knowledge of GitHub, the options I see are the following:
a) Create a preformatted document in each project to be updated manually from time to time.
b) Create a central document to be mantained manually. It was done for 1.5.0 (https://github.com/asciidoctor/asciidoctor.org/tree/master/release-notes) but it's linked in the site under news and it's hard to find. Is the plan to document only major versions?
c) Process GitHub's PR's with some tool. This will require being extremily careful with comments and even some manual tweak before final puiblication.
d) Mixed option (a+c): I like this option because it provides all information and also allow to personalize the content at the cost of more work. As an example I'm looking at groovy's new site http://www.groovy-lang.org/releasenotes/groovy-2.4.html, they document the main changes under different sections and at the end, there's a link to a document with all Jira tickets.

wdyt? Am I overthinking?

mojavelinux

Re: Documenting asciidoctor modules releases

Administrator

You aren't overthinking at all. In fact, this aligns with a conversation we kicked off at Devoxx France about organizing documentation across modules (including release notes). See the notes from the discussion here:

https://github.com/asciidoctor/asciidoctor.org/wiki/DevoxxFR-BOF-Notes

I've been meaning to kick off a discussion on the list to explain what we were talking about and what the next steps are. Your points will play a key role in that discussion. I'll do some thinking and follow-up in more details.

Cheers,

-Dan

On Mon, May 4, 2015 at 12:30 AM, abelsromero [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Hi all,

Many great things are going on and I feel like the need to document releases is getting more and more important everyday. The main problems I see are these:
1. It's hard to keep track of everything.
2. It's hard to elaborate a release document to be used on the blog or the site. This should include improvements as well as bug fixes. The later, imho, even more important.

With my limited knowledge of GitHub, the options I see are the following:
a) Create a preformatted document in each project to be updated manually from time to time.
b) Create a central document to be mantained manually. It was done for 1.5.0 (https://github.com/asciidoctor/asciidoctor.org/tree/master/release-notes) but it's linked in the site under news and it's hard to find. Is the plan to document only major versions?
c) Process GitHub's PR's with some tool. This will require being extremily careful with comments and even some manual tweak before final puiblication.
d) Mixed option (a+c): I like this option because it provides all information and also allow to personalize the content at the cost of more work. As an example I'm looking at groovy's new site http://www.groovy-lang.org/releasenotes/groovy-2.4.html, they document the main changes under different sections and at the end, there's a link to a document with all Jira tickets.

wdyt? Am I overthinking?

If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Documenting-asciidoctor-modules-releases-tp3116.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

Dan Allen | http://google.com/profiles/dan.j.allen

mojavelinux

Re: Documenting asciidoctor modules releases

Administrator

In reply to this post by abelsromero

Abel et al,

I'm still giving thought to the original question, but something came to mind that is related which I've been meaning to discuss.

We should document the recommended labels and milestone names for use in the GitHub issue tracker. Whenever I switch to project, I often find it disruptive for labels and milestones to be missing. Creating them on the spot is more than just an interruption. It introduces inconsistency because we end up with different labels or different label color from one project to the next.

We can use Asciidoctor core as a base, but I'm not necessarily convince we've figured out the best strategy yet. See <https://github.com/asciidoctor/asciidoctor/labels>.

While it's not a requirement that all projects be the same, it is helpful if we generally agree on some core labels and milestones so that it's easier to file and organize issues.

Cheers,

-Dan

Dan Allen | http://google.com/profiles/dan.j.allen

abelsromero

Re: Documenting asciidoctor modules releases

It's really a shame GitHub does not allow to add a description to a label or set them at organization level.

Meanwhile, I guess we could create a page on the wiki (https://github.com/asciidoctor/asciidoctor/wiki) describing
a basic set of labels, their usage and use cases. This article should be linked on each README, that way people can better understand each issue state.

Should we start a new conversation (in the forum) to define the labels and descriptions?

mojavelinux

Re: Documenting asciidoctor modules releases

Administrator

Abel wrote:

It's really a shame GitHub does not allow to add a description to a label or set them at organization level.

I had the same thought...many times.

Meanwhile, I guess we could create a page on the wiki (https://github.com/asciidoctor/asciidoctor/wiki) describing
a basic set of labels, their usage and use cases. This article should be linked on each README, that way people can better understand each issue state.

Should we start a new conversation (in the forum) to define the labels and descriptions?

Sounds like a good plan!

-Dan

Dan Allen | http://google.com/profiles/dan.j.allen

abelsromero

Re: Documenting asciidoctor modules releases

As proposed I have create an analysis of the current tags used in asciidoctor in a wiki page: https://github.com/asciidoctor/asciidoctor/wiki/Label-usage-for-GitHub-projects-(WIP).

There are some labels whose meaning I quite don't see, they marked as ?. Please Dan or anyone with the knowledge, if you can add some notes I will update the document.

What I would like to get is a minimum set of labels to be used in a normal project and put them in practice in asciidoctorJ (I say normal, because asciidoctor or arciidoctor.org have some peculiarities).
Once they are in practice It would be simple to automate the creating of release notes using GitHub REST API Issues, but we need to set the meaning of the labels to categorize them.

LightGuardjp

Re: Documenting asciidoctor modules releases

I think the link was bad in your email, please use https://github.com/asciidoctor/asciidoctor/wiki/Label-usage-for-GitHub-projects-%28WIP%29

Here's my take on the question marked areas:

* compliance - Back in earlier releases, not so much any more we'd have issues with being compliant with AsciiDoc python. This label was used to track those issues.
* next - Often if we're not sure what the next release will be we'll tag something as "next" meaning it'll be in whatever the next release is. Really it's just a bucket to put things in we want to cover soon but aren't sure where exactly to put them.
* withdrawn - I'd say this is just to keep a list of "won't fix" issues
* blocker - There could still be blockers to the next release, worth keeping around

* unknown - probably just something to mark an issue as something to look into further

On Thu, Aug 20, 2015 at 11:57 AM, abelsromero [via Asciidoctor :: Discussion] <[hidden email]> wrote:

As proposed I have create an analysis of the current tags used in asciidoctor in a wiki page: https://github.com/asciidoctor/asciidoctor/wiki/Label-usage-for-GitHub-projects-(WIP).

There are some labels whose meaning I quite don't see, they marked as ?. Please Dan or anyone with the knowledge, if you can add some notes I will update the document.

What I would like to get is a minimum set of labels to be used in a normal project and put them in practice in asciidoctorJ (I say normal, because asciidoctor or arciidoctor.org have some peculiarities).
Once they are in practice It would be simple to automate the creating of release notes using GitHub REST API Issues, but we need to set the meaning of the labels to categorize them.

If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Documenting-asciidoctor-modules-releases-tp3116p3698.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

Jason Porter
http://en.gravatar.com/lightguardjp

abelsromero

Re: Documenting asciidoctor modules releases

I just updated the document. Thank you for the comments and Jakub for the revision.