Skip to content

Latest commit

 

History

History
108 lines (84 loc) · 12.1 KB

CONTRIBUTING.md

File metadata and controls

108 lines (84 loc) · 12.1 KB
Raw

Contributing

Public Participation Invited

This OASIS TC Open Repository ( github.com/oasis-open/tosca-test-assertions ) is a community public repository that supports participation by anyone, whether affiliated with OASIS or not. Substantive contributions (repository "code") and related feedback is invited from all parties, following the common conventions for participation in GitHub public repository projects. Participation is expected to be consistent with the OASIS TC Open Repository Guidelines and Procedures, the LICENSE designated for this particular repository (Apache License v 2.0), and the requirement for an Individual Contributor License Agreement. Please see the repository README document for other details.

Governance Distinct from OASIS TC Process

Content accepted as "contributions" to this TC Open Repository, as defined below, are distinct from any Contributions made to the associated OASIS Topology and Orchestration Specification for Cloud Applications (TOSCA) TC itself. Participation in the associated Technical Committee is governed by the OASIS Bylaws, OASIS TC Process, IPR Policy, and related policies. This TC Open Repository is not subject to the OASIS TC-related policies. TC Open Repository governance is defined by separate participation and contribution guidelines as referenced in the OASIS TC Open Repositories Overview.

Licensing Distinct from OASIS IPR Policy

Because different licenses apply to the OASIS TC's specification work, and this TC Open Repository, there is no guarantee that the licensure of specific repository material will be compatible with licensing requirements of an implementation of a TC's specification. Please refer to the LICENSE file for the terms of this material, and to the OASIS IPR Policy for the terms applicable to the TC's specifications, including any applicable declarations.

Contributions Subject to Individual CLA

Formally, "contribution" to this TC Open Repository refers to content merged into the "Code" repository (repository changes represented by code commits), following the GitHub definition of contributor: "someone who has contributed to a project by having a pull request merged but does not have collaborator [i.e., direct write] access." Anyone who signs the TC Open Repository Individual Contributor License Agreement (CLA), signifying agreement with the licensing requirement, may contribute substantive content — subject to evaluation of a GitHub pull request. The main web page for this repository, as with any GitHub public repository, displays a link to a document listing contributions to the repository's default branch (filtered by Commits, Additions, and Deletions).

This TC Open Repository, as with GitHub public repositories generally, also accepts public feedback from any GitHub user. Public feedback includes opening issues, authoring and editing comments, participating in conversations, making wiki edits, creating repository stars, and making suggestions via pull requests. Such feedback does not constitute an OASIS TC Open Repository contribution. Some details are presented under "Read permissions" in the table of permission levels for a GitHub organization. Technical content intended as a substantive contribution (repository "Code") to an TC Open Repository is subject to evaluation, and requires a signed Individual CLA.

Fork-and-Pull Collaboration Model

OASIS TC Open Repositories use the familiar fork-and-pull collaboration model supported by GitHub and other distributed version-control systems. Any GitHub user wishing to contribute should fork the repository, make additions or other modifications, and then submit a pull request. GitHub pull requests should be accompanied by supporting comments and/or issues. Community conversations about pull requests, supported by GitHub notifications, will provide the basis for a consensus determination to merge, modify, close, or take other action, as communicated by the repository Maintainers.

Feedback

Questions or comments about this TC Open Repository's activities should be composed as GitHub issues or comments. If use of an issue/comment is not possible or appropriate, questions may be directed by email to the repository Maintainer(s). Please send general questions about TC Open Repository participation to OASIS Staff at [email protected] and any specific CLA-related questions to [email protected].

Contribution Guide

Pull requests in order to be properly validated and accepted should follow the constraints defined below:

  • Pull requests should not contains too many tests as it will take longer to review them. They also may be rejected even if only a single test is rejected..
  • If a pull-request define multiple tests they must all be variants aiming to validate the same element of the specification
  • The test template must be placed in the folder matching the conformance target (Parser-Validator or Orchestrator)
  • The test template can be a yaml TOSCA template OR an unzipped TOSCA archive in a folder.
  • The TOSCA template or Archive's entry TOSCA template must contains a metadata section that defines the test assertion expected from parsing the template as defined bellow:
metadata:
  oasis.testAssertion.id: <test assertion id>
  oasis.testAssertion.description: <description>
  oasis.testAssertion.prerequisite: <optional prerequisite>
  oasis.testAssertion.target: <required target>
  oasis.testAssertion.predicate: <required predicate>
  oasis.testAssertion.tags.errors: <optional error_code>, <optional error_code>
  oasis.testAssertion.tags.errors_lines: <optional error_line>, <optional error_line>
  oasis.testAssertion.prescription_level: <required level>
  oasis.testAssertion.normativeSource.refSourceItem.documentId: <required id of the normative source under test>
  oasis.testAssertion.normativeSource.refSourceItem.versionId: <required version of the normative source>
  oasis.testAssertion.normativeSource.textSourceItem.section: <required section>
  oasis.testAssertion.normativeSource.textSourceItem.line: <optional line>
  oasis.testAssertion.tags.conformancetarget: <required conformance target>

  • Where:

    • <test assertion id>: unique id of the test assertion and must follow the following pattern: <oasis.testAssertion.normativeSource.textSourceItem.section>-<element under test>-<test variant id>-<optional short description>.
    • <optional prerequisite>: association (corresponding to the Prerequisite termin- ology definition) expresses a pre-condition to be satisfied by the <Target> in order to qualify for the test expressed by the <Predicate>. It is a boolean expression: if evaluates to "true", the <Predicate> can be evaluated over the <Target>. If evaluates to "false", the <Target> is not qualified for this test assertion.
    • <required target> target that will be validated by the predicate.
    • <required predicate>: association (corresponding to the Predicate terminology definition) expresses the feature or behavior expected from the <Target> as stated in <NormativeSource>. It is a boolean expression: if evaluates to "true", the <Target> instance exhibits the expected feature. If "false", the <Target> does not.
    • <optional error_code> is a coma separated list of error codes (also expressed in the predicate) in case of expected parsing errors.
    • <optional error_line> is a coma separated list of error lines in the document the list of line numbers must match the list of error codes in the errors section.
    • <required level> the level of prescription of the test (mandatory, preferred or permitted).
    • <required id of the normative source under test> Id of the normative source targeted by the test assertion (tosca_simple_yaml_1_0).
    • <required version of the normative source> Version of the normative source targeted by the test assertion (1.0.0).
    • <required section> Number of the section in the normative source.
    • <optional line> Optional line from the normative source.
    • <required conformance target> the tool that is targeted by the test assertion Parser-Validator or Orchestrator.

  • Example:

metadata:
  oasis.testAssertion.id: 3.1.2-tosca_definitions_version-01-valid-definition
  oasis.testAssertion.description: Parsing a document with valid tosca definition version MUST succeed.
  oasis.testAssertion.target: a tosca template that has a valid tosca_definitions_version value equals to 'tosca_simple_yaml_1_0'.
  oasis.testAssertion.predicate: >
    When parsing the template
    assert 'tosca_definitions_version' value is equal to 'http://docs.oasis-open.org/tosca/ns/simple/yaml/1.0' or 'tosca_simple_yaml_1_0'
  oasis.testAssertion.prescription_level: mandatory
  oasis.testAssertion.normativeSource.refSourceItem.documentId: tosca_simple_yaml_1_0
  oasis.testAssertion.normativeSource.refSourceItem.versionId: 1.0.0
  oasis.testAssertion.normativeSource.textSourceItem.section: 3.1.2
  oasis.testAssertion.tags.conformancetarget: Parser-Validator
  • The name of the TOSCA template or archive folder MUST be equal to the test assertion id (for example 3.1.2-tosca_definitions_version-01-valid-definition.yml):
  • The predicate expression must follow the following patterns:
    • assert <target> value is equal to <expected value> (or <other expected value> ...)
    • assert raises the error <error_id> (and error <error_id> ...)