groups:
  - id: registry.vcs.repository
    type: attribute_group
    display_name: VCS Repository Attributes
    brief: >
      This group defines the attributes for
      [Version Control Systems (VCS)](https://wikipedia.org/wiki/Version_control).
    attributes:
      - id: vcs.repository.url.full
        type: string
        stability: development
        brief: >
          The [canonical URL](https://support.google.com/webmasters/answer/10347851?hl=en#:~:text=A%20canonical%20URL%20is%20the,Google%20chooses%20one%20as%20canonical.)
          of the repository providing the complete HTTP(S) address in order to
          locate and identify the repository through a browser.
        note: |
          In Git Version Control Systems, the canonical URL SHOULD NOT include
          the `.git` extension.
        examples:
          [
            "https://github.com/opentelemetry/open-telemetry-collector-contrib",
            "https://gitlab.com/my-org/my-project/my-projects-project/repo",
          ]
      - id: vcs.repository.name
        type: string
        stability: development
        brief: >
          The human readable name of the repository. It SHOULD NOT include any
          additional identifier like Group/SubGroup in GitLab or organization
          in GitHub.
        note: |
          Due to it only being the name, it can clash with forks of the same
          repository if collecting telemetry across multiple orgs or groups in
          the same backends.
        examples:
          [
            "semantic-conventions",
            "my-cool-repo",
          ]
      - id: vcs.ref.base.name
        type: string
        stability: development
        brief: >
          The name of the
          [reference](https://git-scm.com/docs/gitglossary#def_ref) such as
          **branch** or **tag** in the repository.
        note: |
          `base` refers to the starting point of a change. For example, `main`
          would be the base reference of type branch if you've created a new
          reference of type branch from it and created new commits.
        examples: ["my-feature-branch", "tag-1-test"]
      - id: vcs.ref.base.type
        type:
          members:
            - id: branch
              value: branch
              brief: "[branch](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch)"
              stability: development
            - id: tag
              value: tag
              brief: "[tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag)"
              stability: development
        stability: development
        brief: >
          The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository.
        note: |
          `base` refers to the starting point of a change. For example, `main`
          would be the base reference of type branch if you've created a new
          reference of type branch from it and created new commits.
        examples: ["branch", "tag"]
      - id: vcs.ref.base.revision
        type: string
        stability: development
        brief: >
          The revision, literally [revised version](https://www.merriam-webster.com/dictionary/revision),
          The revision most often refers to a commit object in Git, or a revision number in SVN.
        note: |
          `base` refers to the starting point of a change. For example, `main`
          would be the base reference of type branch if you've created a new
          reference of type branch from it and created new commits. The
          revision can be a full [hash value (see
          glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf),
          of the recorded change to a ref within a repository pointing to a
          commit [commit](https://git-scm.com/docs/git-commit) object. It does
          not necessarily have to be a hash; it can simply define a [revision
          number](https://svnbook.red-bean.com/en/1.7/svn.tour.revs.specifiers.html)
          which is an integer that is monotonically increasing. In cases where
          it is identical to the `ref.base.name`, it SHOULD still be included.
          It is up to the implementer to decide which value to set as the
          revision based on the VCS system and situational context.
        examples:
          [
            "9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc",
            "main",
            "123",
            "HEAD",
          ]
      - id: vcs.ref.head.name
        type: string
        stability: development
        brief: >
          The name of the
          [reference](https://git-scm.com/docs/gitglossary#def_ref) such as
          **branch** or **tag** in the repository.
        note: |
          `head` refers to where you are right now; the current reference at a
          given time.
        examples: ["my-feature-branch", "tag-1-test"]
      - id: vcs.ref.head.type
        type:
          members:
            - id: branch
              value: branch
              brief: "[branch](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch)"
              stability: development
            - id: tag
              value: tag
              brief: "[tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag)"
              stability: development
        stability: development
        brief: >
          The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository.
        note: |
          `head` refers to where you are right now; the current reference at a
          given time.
        examples: ["branch", "tag"]
      - id: vcs.ref.head.revision
        type: string
        stability: development
        brief: >
          The revision, literally [revised version](https://www.merriam-webster.com/dictionary/revision),
          The revision most often refers to a commit object in Git, or a revision number in SVN.
        note: |
          `head` refers to where you are right now; the current reference at a
          given time.The revision can be a full [hash value (see
          glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf),
          of the recorded change to a ref within a repository pointing to a
          commit [commit](https://git-scm.com/docs/git-commit) object. It does
          not necessarily have to be a hash; it can simply define a [revision
          number](https://svnbook.red-bean.com/en/1.7/svn.tour.revs.specifiers.html)
          which is an integer that is monotonically increasing. In cases where
          it is identical to the `ref.head.name`, it SHOULD still be included.
          It is up to the implementer to decide which value to set as the
          revision based on the VCS system and situational context.
        examples:
          [
            "9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc",
            "main",
            "123",
            "HEAD",
          ]
      - id: vcs.ref.type
        type:
          members:
            - id: branch
              value: branch
              brief: "[branch](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch)"
              stability: development
            - id: tag
              value: tag
              brief: "[tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag)"
              stability: development
        stability: development
        brief: >
          The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository.
        examples: ["branch", "tag"]
      - id: vcs.revision_delta.direction
        type:
          members:
            - id: behind
              value: behind
              brief: "How many revisions the change is behind the target ref."
              stability: development
            - id: ahead
              value: ahead
              brief: "How many revisions the change is ahead of the target ref."
              stability: development
        stability: development
        brief: >
          The type of revision comparison.
        examples: ["ahead", "behind"]
      - id: vcs.line_change.type
        type:
          members:
            - id: added
              value: added
              brief: "How many lines were added."
              stability: development
            - id: removed
              value: removed
              brief: "How many lines were removed."
              stability: development
        stability: development
        brief: >
          The type of line change being measured on a branch or change.
        examples: ["added", "removed"]
      - id: vcs.change.title
        type: string
        stability: development
        brief: >
          The human readable title of the change (pull request/merge request/changelist).
          This title is often a brief summary of the change and may get merged
          in to a ref as the commit summary.
        examples:
          [
            "Fixes broken thing",
            "feat: add my new feature",
            "[chore] update dependency",
          ]
      - id: vcs.change.id
        type: string
        stability: development
        brief: >
          The ID of the change (pull request/merge request/changelist) if applicable. This
          is usually a unique (within repository) identifier generated by the VCS system.
        examples: ["123"]
      - id: vcs.change.state
        type:
          members:
            - id: open
              value: open
              brief: "Open means the change is currently active and under review. It hasn't been merged into the target branch yet, and it's still possible to make changes or add comments."
              stability: development
            - id: wip
              value: wip
              brief: "WIP (work-in-progress, draft) means the change is still in progress and not yet ready for a full review. It might still undergo significant changes."
              stability: development
            - id: closed
              value: closed
              brief: >-
                Closed means the merge request has been closed without merging. This can happen for various reasons, such as the changes being deemed unnecessary,
                the issue being resolved in another way, or the author deciding to withdraw the request.
              stability: development
            - id: merged
              value: merged
              brief: "Merged indicates that the change has been successfully integrated into the target codebase."
              stability: development
        stability: development
        brief: >
          The state of the change (pull request/merge request/changelist).
        examples: ["open", "closed", "merged"]
      - id: vcs.owner.name
        type: string
        stability: development
        brief: >
           The group owner within the version control system.
        examples:
          [
            "my-org",
            "myteam",
            "business-unit",
          ]
      - id: vcs.provider.name
        type:
          members:
            - id: github
              value: github
              brief: "[GitHub](https://github.com)"
              stability: development
            - id: gitlab
              value: gitlab
              brief: "[GitLab](https://gitlab.com)"
              stability: development
            - id: gittea
              value: gittea
              brief: "Deprecated, use `gitea` instead."
              deprecated:
                reason: renamed
                renamed_to: "gitea"
              stability: development
            - id: gitea
              value: gitea
              brief: "[Gitea](https://gitea.io)"
              stability: development
            - id: bitbucket
              value: bitbucket
              brief: "[Bitbucket](https://bitbucket.org)"
              stability: development
        stability: development
        brief: >
          The name of the version control system provider.
        examples:
          [
            "github",
            "gitlab",
            "gitea",
            "bitbucket",
          ]
