Mailing List Archive

Hello Lars,

> Any comments?

Most definitely. Please see below.

> Let me summarize the steps that I want to take here:
>
> - Convert the "current" RA meta-data definition (DTD) to a Relax NG
> schema.
>
> A very basic draft is attached; I dropped the dependency/special
> elements though, since nobody was using them. Before I proceed here:
> is everyone alright with Relax-NG, or is a different format
> preferable?

RelaxNG is definitely better than a DTD, but the DTD works for now. So I
see no point in discussing a conversion here. May I humbly suggest that
we update the "prose" spec first, then work out the RelaxNG schema. I
fear that if we do otherwise, we'll get stuck in a technical discussion
about schema details for the _existing_ spec, delaying the important
task at hand.

> - Make sure our current RAs all still validate ;-)

This step is moot if we go with what works now.

> - Florian, when updating the "descriptive" text, instead of keeping it
> separate, this could directly be merged with The OCF Resource Agent
> Developer’s Guide?

I'd like to hear others' opinions, but my hunch is that they be best
kept in separate documents. The reason is simple: we won't change the
spec without long discussions. For the dev guide, I'm more inclined to
make quick fixes based on a good practice that someone shares on IRC,
and everyone quickly agrees that it's a good idea.

To put it in more softwareish terms: I would anticipate that the spec is
on a much longer release cycle than the dev guide.

I would, however, suggest that both documents share the same format;
asciidoc has proven to be amazingly useful. So, going back to the issue
above: if you do insist on converting something into a better format,
skip the DTD and convert the spec text into asciidoc instead (it's a
dead simple format -- check out the RA dev guide sources).

> Where is the master copy of that maintained? Any thoughts on this?

Currently in http://hg.linux-ha.org/doc but I have no objections to
putting the dev guide (and the spec) in a more appropriate place if we
can agree on one.

> - Put everything up on github; however, github might not be the best
> place for an "official" specification in the long run, but we still
> control the opencf.org domains anyway, so we can eventually place it
> there.

I think github is fine for hosting the repository. I suppose the
definitive spec, as such, would be a versioned HTML and PDF rendering of
a certain tagged snapshot of the sources in the repo.

Of course, since there is now an LF working group, we could put this on
an LF hosted revision control system instead (is there any other than
git.kernel.org?), but I have come to very much appreciate the tools that
github offers for collaboration and review.

> - Propose, discuss, and incorporate the enhancements to the
> API/meta-data formats discussed over the years.

Yes yes yes please!

Cheers,
Florian

On 2011-06-23T14:50:06, Florian Haas <florian.haas@linbit.com> wrote:

> RelaxNG is definitely better than a DTD, but the DTD works for now. So I
> see no point in discussing a conversion here.

Well, the new extensions will not validate according to the old DTD
anyway. So changing this in one go doesn't actually make anything worse.
And some of the new features that we may want - new data formats,
ordering rules, optional elements, etc - appear somewhat easier to
express in Relax NG.

> May I humbly suggest that we update the "prose" spec first, then work
> out the RelaxNG schema. I fear that if we do otherwise, we'll get
> stuck in a technical discussion about schema details for the
> _existing_ spec, delaying the important task at hand.

I see what you're getting at, but the existing spec wouldn't be touched
per se. Further, the DTD that is included with the agents is already not
the one published on opencf.org. So for some intents and purposes,
we're starting fresh, but staying close to the previous spec.

And yes, we should also discuss the "prose" spec. I just wanted the new
syntax definition to be ready before that (and hoping noone would side
track it into a minutiae discussion whether it translates the old format
perfectly), so that we can accompany the proposed extensions with a
proposed definition too.

> > - Make sure our current RAs all still validate ;-)
> This step is moot if we go with what works now.

No, since either way we'd be changing the existing template.

> I'd like to hear others' opinions, but my hunch is that they be best
> kept in separate documents. The reason is simple: we won't change the
> spec without long discussions. For the dev guide, I'm more inclined to
> make quick fixes based on a good practice that someone shares on IRC,
> and everyone quickly agrees that it's a good idea.
>
> To put it in more softwareish terms: I would anticipate that the spec is
> on a much longer release cycle than the dev guide.

I can live with either. But the spec prose would also be much more
concise, and I was thinking it would make sense to keep it along side
examples and more elaborate explanation.

Of course, one would still need to make sure that no incompatible
revisions are introduced, but that can happen either way. And the spec
schema would indeed be very slow changing.

> I would, however, suggest that both documents share the same format;
> asciidoc has proven to be amazingly useful. So, going back to the issue
> above: if you do insist on converting something into a better format,
> skip the DTD and convert the spec text into asciidoc instead (it's a
> dead simple format -- check out the RA dev guide sources).

Yes, asciidoc as the new format is basically a given here.

> I think github is fine for hosting the repository. I suppose the
> definitive spec, as such, would be a versioned HTML and PDF rendering of
> a certain tagged snapshot of the sources in the repo.

I think the "definitive" spec would basically always be the latest
stable revision of that repository, since its purpose is to explain and
detail the formal schema and return codes.

> > - Propose, discuss, and incorporate the enhancements to the
> > API/meta-data formats discussed over the years.
> Yes yes yes please!

The most important one is probably the ability to depreciate agents.
I'll start a new thread about that.


Regards,
Lars

--
Architect Storage/HA, OPS Engineering, Novell, Inc.
SUSE LINUX Products GmbH, GF: Jeff Hawn, Jennifer Guild, Felix Imendörffer, HRB 21284 (AG Nürnberg)
"Experience is the name everyone gives to their mistakes." -- Oscar Wilde

_______________________________________________
ha-wg-technical mailing list
ha-wg-technical@lists.linux-foundation.org
https://lists.linux-foundation.org/mailman/listinfo/ha-wg-technical

On 06/25/2011 03:54 PM, Lars Marowsky-Bree wrote:
> On 2011-06-23T14:50:06, Florian Haas <florian.haas@linbit.com> wrote:
>
>> RelaxNG is definitely better than a DTD, but the DTD works for now. So I
>> see no point in discussing a conversion here.
>
> Well, the new extensions will not validate according to the old DTD
> anyway. So changing this in one go doesn't actually make anything worse.
> And some of the new features that we may want - new data formats,
> ordering rules, optional elements, etc - appear somewhat easier to
> express in Relax NG.
>
>> May I humbly suggest that we update the "prose" spec first, then work
>> out the RelaxNG schema. I fear that if we do otherwise, we'll get
>> stuck in a technical discussion about schema details for the
>> _existing_ spec, delaying the important task at hand.
>
> I see what you're getting at, but the existing spec wouldn't be touched
> per se. Further, the DTD that is included with the agents is already not
> the one published on opencf.org. So for some intents and purposes,
> we're starting fresh, but staying close to the previous spec.
>
> And yes, we should also discuss the "prose" spec. I just wanted the new
> syntax definition to be ready before that (and hoping noone would side
> track it into a minutiae discussion whether it translates the old format
> perfectly), so that we can accompany the proposed extensions with a
> proposed definition too.

You are, of course, aware that the discussions about proposed extensions
of the spec are reaching beyond just the metadata format.

>> I'd like to hear others' opinions, but my hunch is that they be best
>> kept in separate documents. The reason is simple: we won't change the
>> spec without long discussions. For the dev guide, I'm more inclined to
>> make quick fixes based on a good practice that someone shares on IRC,
>> and everyone quickly agrees that it's a good idea.
>>
>> To put it in more softwareish terms: I would anticipate that the spec is
>> on a much longer release cycle than the dev guide.
>
> I can live with either. But the spec prose would also be much more
> concise, and I was thinking it would make sense to keep it along side
> examples and more elaborate explanation.

Elaborate explanations as to how implementations are supposed to behave
quite definitely belong in the spec proper.

> Of course, one would still need to make sure that no incompatible
> revisions are introduced, but that can happen either way. And the spec
> schema would indeed be very slow changing.
>
>> I would, however, suggest that both documents share the same format;
>> asciidoc has proven to be amazingly useful. So, going back to the issue
>> above: if you do insist on converting something into a better format,
>> skip the DTD and convert the spec text into asciidoc instead (it's a
>> dead simple format -- check out the RA dev guide sources).
>
> Yes, asciidoc as the new format is basically a given here.
>
>> I think github is fine for hosting the repository. I suppose the
>> definitive spec, as such, would be a versioned HTML and PDF rendering of
>> a certain tagged snapshot of the sources in the repo.
>
> I think the "definitive" spec would basically always be the latest
> stable revision of that repository, since its purpose is to explain and
> detail the formal schema and return codes.

Beg to differ; we should allow for the spec being a work in progress
from time to time. Just so long as there _is_ a stable version and we
don't have a permanent provisional draft like we currently do.

Cheers,
Florian

On 2011-06-27T09:22:39, Florian Haas <florian.haas@linbit.com> wrote:

> You are, of course, aware that the discussions about proposed extensions
> of the spec are reaching beyond just the metadata format.

Of course. ;-) But they are not independent either.

> > I can live with either. But the spec prose would also be much more
> > concise, and I was thinking it would make sense to keep it along side
> > examples and more elaborate explanation.
> Elaborate explanations as to how implementations are supposed to behave
> quite definitely belong in the spec proper.

Okay, so lets keep them separate for the time being.

> Beg to differ; we should allow for the spec being a work in progress
> from time to time. Just so long as there _is_ a stable version and we
> don't have a permanent provisional draft like we currently do.

Agreed. Even if it hasn't actually been that much of a problem and is
becoming even less of one since there's only one master implementation
;-)


Regards,
Lars

--
Architect Storage/HA, OPS Engineering, Novell, Inc.
SUSE LINUX Products GmbH, GF: Jeff Hawn, Jennifer Guild, Felix Imendörffer, HRB 21284 (AG Nürnberg)
"Experience is the name everyone gives to their mistakes." -- Oscar Wilde

_______________________________________________
ha-wg-technical mailing list
ha-wg-technical@lists.linux-foundation.org
https://lists.linux-foundation.org/mailman/listinfo/ha-wg-technical

Hi Lars,

On Thu, Jun 23, 2011 at 01:23:06PM +0200, Lars Marowsky-Bree wrote:
> Hi all,
>
> sincere apologies for the close-to-infinite delay on this task.
>
> Let me summarize the steps that I want to take here:
>
> - Convert the "current" RA meta-data definition (DTD) to a Relax NG
> schema.
>
> A very basic draft is attached; I dropped the dependency/special
> elements though, since nobody was using them. Before I proceed here:
> is everyone alright with Relax-NG, or is a different format
> preferable?

I agree with Florian that this is not essential, but really
don't mind about the order.

> - Make sure our current RAs all still validate ;-)
>
> - Florian, when updating the "descriptive" text, instead of keeping it
> separate, this could directly be merged with The OCF Resource Agent
> Developer’s Guide?

I think that they should be separate. The Guide is about how to
implement an RA, and that mostly in shell.

> Where is the master copy of that maintained? Any thoughts on this?
>
> - Put everything up on github; however, github might not be the best
> place for an "official" specification in the long run, but we still
> control the opencf.org domains anyway, so we can eventually place it
> there.

I don't think this may be necessary. Let's hope that the
standard won't be changing more than once a year.

> - Propose, discuss, and incorporate the enhancements to the
> API/meta-data formats discussed over the years.
>
> Any comments?

How about standardizing RA testing too? Perhaps even adding a
kind of (possibly two-step) self-testing facility.

Cheers,

Dejan

>
> Regards,
> Lars
>
> --
> Architect Storage/HA, OPS Engineering, Novell, Inc.
> SUSE LINUX Products GmbH, GF: Jeff Hawn, Jennifer Guild, Felix Imendörffer, HRB 21284 (AG Nürnberg)
> "Experience is the name everyone gives to their mistakes." -- Oscar Wilde
>

> <?xml version="1.0" encoding="utf-8"?>
> <!-- types: http://www.w3.org/TR/xmlschema-2/#dateTime -->
> <grammar xmlns="http://relaxng.org/ns/structure/1.0"
> datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes">
> <start>
> <ref name="element-resource-agent"/>
> </start>
>
> <define name="element-resource-agent">
> <element name="resource-agent">
> <attribute name="id"><data type="ID"/></attribute>
> <optional>
> <attribute name="version"><text/></attribute>
> </optional>
> <oneOrMore>
> <choice>
> <element name="longdesc"><ref name="attribute-desc"/></element>
> <element name="shortdesc"><ref name="attribute-desc"/></element>
> </choice>
> </oneOrMore>
> <element name="parameters">
> <zeroOrMore>
> <ref name="element-parameter"/>
> </zeroOrMore>
> </element>
> <element name="actions">
> <oneOrMore>
> <ref name="action"/>
> </oneOrMore>
> </element>
> </element>
> </define>
>
> <define name="parameter">
> <attribute name="name"><text/></attribute>
> <optional>
> <attribute name="required"><data type="boolean"/></attribute>
> </optional>
> <optional>
> <attribute name="unique"><data type="boolean"/></attribute>
> </optional>
> <oneOrMore>
> <choice>
> <element name="longdesc"><ref name="attribute-desc"/></element>
> <element name="shortdesc"><ref name="attribute-desc"/></element>
> </choice>
> </oneOrMore>
> <ref name="element-content"/>
> </define>
>
> <define name="element-content">
> <element name="content">
> <attribute name="type">
> <choice>
> <value>string</value>
> <value>integer</value>
> <value>boolean</value>
> </choice>
> </attribute>
> <attribute name="required"><data type="boolean"/></attribute>
> <optional>
> <attribute name="default"><text/></attribute>
> </optional>
> </element>
> </define>
>
> <define name="element-action">
> <element name="action">
> <attribute name="name">
> <choice>
> <value>demote</value>
> <value>meta-data</value>
> <value>monitor</value>
> <value>notify</value>
> <value>promote</value>
> <value>recover</value>
> <value>reload</value>
> <value>start</value>
> <value>status</value>
> <value>stop</value>
> <value>verify-all</value>
> </choice>
> </attribute>
> <attribute name="timeout"><data type="nonNegativeInteger"/></attribute>
> <optional>
> <attribute name="interval"><data type="nonNegativeInteger"/></attribute>
> </optional>
> <optional>
> <attribute name="start-delay"><data type="nonNegativeInteger"/></attribute>
> </optional>
> <optional>
> <attribute name="depth"><data type="nonNegativeInteger"/></attribute>
> </optional>
> </element>
> </define>
>
> <define name="attribute-desc">
> <optional>
> <attribute name="lang"><text/></attribute>
> </optional>
> <text/>
> </define>
>

> _______________________________________________
> ha-wg-technical mailing list
> ha-wg-technical@lists.linux-foundation.org
> https://lists.linux-foundation.org/mailman/listinfo/ha-wg-technical

_______________________________________________
ha-wg-technical mailing list
ha-wg-technical@lists.linux-foundation.org
https://lists.linux-foundation.org/mailman/listinfo/ha-wg-technical

On 2011-06-28T16:43:09, Dejan Muhamedagic <dejan@suse.de> wrote:

Hi Dejan,

> How about standardizing RA testing too? Perhaps even adding a
> kind of (possibly two-step) self-testing facility.

I'm not sure I understand what you're suggesting here. Can you clarify
that please?


Regards,
Lars

--
Architect Storage/HA, OPS Engineering, Novell, Inc.
SUSE LINUX Products GmbH, GF: Jeff Hawn, Jennifer Guild, Felix Imendörffer, HRB 21284 (AG Nürnberg)
"Experience is the name everyone gives to their mistakes." -- Oscar Wilde

_______________________________________________
ha-wg-technical mailing list
ha-wg-technical@lists.linux-foundation.org
https://lists.linux-foundation.org/mailman/listinfo/ha-wg-technical