Skip to content

Organization Documentation

Terminology and Conventions

This section outlines key terms, phrases, and writing rules used in Margo's specifications. Understanding these is crucial for correct interpretation and application of the standard. Knowing these elements helps users better understand and use the specifications, leading to more effective implementation of the guidelines.

Terminology and Conventions
  • **Language**: The default language for writing documentation is American English, English (United States).
  • **Conventions**: The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC2119].
  • **MUST**:This word, or the terms "REQUIRED" or "SHALL", mean that the definition is an absolute requirement of the specification.
  • **SHOULD**: This word, or the adjective "RECOMMENDED", means that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course.
  • ****MAY**:**:This word, or the adjective "OPTIONAL", means that an item is truly optional. One vendor may choose to include the item because a particular marketplace requires it or because the vendor feels that it enhances the product while another vendor may omit the same item. An implementation which does not include a particular option MUST be prepared to interoperate with another implementation which does include the option, though perhaps with reduced functionality. In the same vein, an implementation which does include a particular option MUST be prepared to interoperate with another implementation which does not include the option (except, of course, for the feature the option provides.)

Definitions

Specification Definitions and Terminology: A comprehensive glossary of terms and concepts used in the development and documentation of specifications within our organization. This resource provides clear and concise explanations of key terminology, ensuring consistency and clarity across all project documentation and communications.

  • Definitions
    Committee Team A group chartered by the Steering Committee to perform specific support tasks
    Editor(s) A member of a Working Group who is responsible for editing and maintaining a document.
    e-Vote Electronic Vote.
    Issue(s) An important topic or problem for debate or discussion. Normally, Issues are tracked in Github.
    Maintainer A member of the Organization selected by the Working Group as a coordinator for the Working Group activities.
    A Maintainer is the person (or persons) *responsible for the direction or movement* of an Organization Working Group. He/she/they are committed to improving, driving, and ensuring an outcome.
    A Maintainer doesn’t necessarily have to be someone who writes the data specification. It could be someone who’s done a lot of work evangelizing the Organization or written documentation that made the Organization more accessible to others. Regardless of what they do day-to-day, a Maintainer is probably someone who feels responsibility for the direction of the project and is committed to improving it.
    A maintainer is the final control point for contributions to a specification. Typically, Pull Requests will be proposed by members and approved by the working group following consensus rules. The maintainer ensures the contribution rules are followed and that consensus has been met, especially for controversial or disputed contributions. The maintainer(s) should be the ones that merge the PR into the baseline .
    Member(s) A person that belongs to a company that has signed the Organization Membership Application, Project and Working Group Charter(s)
    Membership Application A document that provides legal information about the rights and obligations of being a member company of the Organization.
    Participant A Participant is any individual creating content or commenting on an Issue or Pull Request.
    Project Charter A legal document that describes the Organization Project.
    Pull Request It indicates what changes are suggested to a branch in a repository on GitHub.
    Release It is the distribution of the final version of a document or application.
    Review & Approval A special process used to convey agreement or disagreement on a topic.
    Semantic Versioning It is a versioning scheme to convey backwards or not backwards compatibility of a release.
    Source Code It is any collection of code, with or without comments, written using a human-readable programming language, usually plain text.
    Specification(s) An act of describing or identifying something precisely or stating a precise requirement.
    Steering Committee A committee that decides on the priorities or order of business of the Organization.
    Working Group A group of experts working together to achieve predefined objectives. The group formalize its objectives and goals in a formal document, the Working Group Charter.
    Working Group Maintainer A person selected by the Working Group whose primary role is facilitating consensus-building among the group members.
    Working Group Charter A document containing a particular group's scope, objectives and goals.
    Work Package It is a group of related tasks within a project. Each Work Package can be broken down into one or more groups.

Semantic Versioning

Semantic Versioning provides a structured and systematic approach to managing software versions, enabling developers to communicate changes effectively and maintain compatibility across different releases. This system offers a clear set of rules and conventions for version number assignment, facilitating smoother collaboration and easier dependency management in software development projects.

Semantic Versioning
Semantic Versioning
  • Document Version
    Field Use Description
    X Major Version Indicator This mandatory field SHALL identify the major version of the document as determined by the WG. Major versions contain major feature additions, MAY contain incompatibilities with previous document or specification revisions and MAY change, drop, or replace existing interfaces. Initial releases are “1_0”.
    Y Minor Version Indicator Minor version of the document. This mandatory field SHALL identify the minor version of the document. It is incremented every time a minor change is made to the approved document version. Minor versions MAY contain minor feature additions, are compatible with the preceding Major_Minor specification revision, and provide evolving interfaces. The initial minor release for any major release is “0”, i.e. 1_0
    Z Service Indicator Service indicator for the document. Incremented every time a corrective update is made to the Approved (not draft) document version by the WG. This field is OPTIONAL and SHALL be provided whenever a service release of the document is made. The first service indicator release SHALL be “_1” for any Major_Minor release. Service indicators are intended to be compatible with the Major_Minor release they relate to but add bug fixes. No new functions will be added through the release of Service Indicators.