Skip to content

Latest commit

 

History

History
186 lines (136 loc) · 10.4 KB

CONTRIBUTING.md

File metadata and controls

186 lines (136 loc) · 10.4 KB
Raw

Contributing to hl7-at-fhir-profiles

The following is a set of guidelines for contributing to the hl7-at-fhir-profiles project and its packages, which are hosted in the HL7-Austria organization on GitHub. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.

Code of Conduct

This project and everyone participating in it is governed by HL7 Austria FHIR Technical Committee. By participating, you are expected to uphold this code. Please report unacceptable behavior to [email protected].

How Can I Contribute?

There are multiple ways of how one can contribute to the efforts of the TC FHIR from HL7 Austria:

  • Active participation on the HL7 Austria TC FHIR conference calls
  • Creating feature requests or bug reports on github
  • For questions and broader discussions, use the TC-Austria channel on Zulip

Reporting Bugs

  • For reporting bugs the TC FHIR created an issue template for github, it can be found here and is available automatically if a new issue is created.

Before Submitting A Bug Report

  • Please make sure if there isn't already an open or closed github issue in the HL7 Austria repository for the problem that you are facing. If the problem isn't directly related to HL7 Austria FHIR profiles or extensions but is more general, please also make sure that it hasn't be dealt with on the official [FHIR Chat] (https://chat.fhir.org).

How Do I Submit A (Good) Bug Report?

  • In order to create a good bug report you will be asked to fill out a couple of questions concerning your bug, which are necessary for the TC FHIR in order to address the stated problem most effectively.
Bug Criteria Description
Real Submitter Who ist the real submitter, in case the creation of the issue was done by proxy.
Resource(s)/Profiles incl. Version Which resources or profiles are affected by this bug report?
Priority Priority of this bug report (Blocker, Critical, Major, Minor, Trivial).
Describe the bug A clear and concise description of what the bug is.
To Reproduce Steps to reproduce the behavior.
Expected behavior A clear and concise description of what you expected to happen.

Request New Profiles/Extensions

  • For requesting new Profiles or Extensions or features in general the TC FHIR created a feature request template for github, it can be found here and is available automatically if a new issue is created.
  • Alternatively a new Profile or an Extension can be requested by sending an email to tc-fhir
  • Use the issue to describe the intended use case and if applicable state some examples.

How Do I Submit a (Good) Enhancement

  • In order to create a good feature request you will be asked to fill out a couple of questions concerning your request, which are necessary for the TC FHIR in order to address the desired feature most effectively.
Request Criteria Description
Real Submitter Who ist the real submitter, in case the creation of the issue was done by proxy.
Resource(s)/Profiles incl. Version Which resources or profiles are affected by this bug report?
Priority Priority of this request (Blocker, Critical, Major, Minor, Trivial).
Is your feature request related to a problem? Please describe. A clear and concise description of what the problem is.
Describe the solution you'd like A clear and concise description of what you want to happen.
Describe alternatives you've considered A clear and concise description of any alternative solutions or features you've considered.

Issue and Pull Request Labels

Label name Description
discussion needs to be discussed in a meeting of the technical committee FHIR in HL7 Austria
review a solution to an open issue is provided, however the solution has to be reviewed before closing respective issue
bug marks a bug in the implementation
enhancement propose a new feature or a change in an existing profile/extension
blocked issues marked with blocked are dependent on other issue still in progress
hot marks issues with high priority, these are only assigned by the HL7 Austria TC-FHIR, any invalid use on issues will be removed without discussion

Style guides

Git Commit Messages

A commit message must start with the corresponding ticket number in GitHub (#TICKETNUMBER) each commit message must have a description which should be in present tense and use imperative voice

Naming Conventions

In general the HL7 FHIR naming conventions apply. Essentially these conventions ask for consistency and precision (i.e. minimizing ambiguity, while ensuring the meaning is easily understood) when naming fields, resources or operations.

Most of these guidelines are suggestions, except the following rules that must be followed:

  • be U.S. English (spelled correctly!)
  • be expressed as a noun, with a preceding adjective where necessary to clarify the semantics and to make unique
  • not make use of trade-marked terms
  • case style must be followed:
    • resources must be lower case - ex. at-core-patient, patient resource is all lower case
    • elements must be lowerCamelCase - ex. at-core-ext-address-additionalInformation, the element address.additionalInformation is lowerCamelCase
    • operations must be lower case - e. at-core-exampleoperation example operation is all lower case

Profile Naming conventions

The StructureDefintion Id of a profile follows a prefix pattern, meaning that a name from left to right goes from specific to generic. It uses UpperCamelCase.

ProfileName = [Realm-], Use-, ParentProfile

Realm = Is this profile supposed to be used in a realm? Then use the countryCode1

Use = What is this profile used for? lower case

ParentProfile = Which profile does this profile extend from? lower case

Example: Patient used in Austria, for ELGA.

Realm = Austria -> at- (country code)
Use = HL7 Austria FHIR Core -> core-
ParentProfile = Patient -> patient
at-core-patient

Example: Immunization information for ELGA

Realm = Austria -> at-
Use = ELGA -> elga-
ParentProfile = Immunization -> immunization
at-elga-immunization

Extension Naming conventions

The StructureDefintion Id of an extension follows a suffix pattern, meaning that a name from left to right goes from generic to specific.

ExtensionName = [Realm-], Use-, ext- ProfileItIsFor-, FieldItAdds

Realm = Is this profile supposed to be used in a realm? Then use the countryCode1

Use = What is this profile used for? lower case

ext- = indication that this is an Extension lower case

ProfileItIsFor = Either Base Profile or Profile previously defined (optional if extension can occur anywhere -> Ex. NullFlavor), without the Realm. lower case

FieldItAdds = unique naming for field lowerCamelCase

Example: Religions for a patient registered in Austria

Realm = Austria -> at-
Use = HL7 Austria FHIR Core -> core-
Profile = Patient -> patient-
FieldItAdds = Religion -> religion
at-core-ext-patient-religion

Example: Extra field in Address

Realm = Austria -> at-
Use = HL7 Austria FHIR Core -> core-
Profile = Address -> address
FieldItAdds = Additional Information -> additionalInformation
at-core-ext-address-additionalInformation

Additional Information

Documentation of decisions on issues

HL7 International is documenting the decision it makes on issues in it's ticket tracker tool gforge. For HL7 Austria we've decided to use their way of documenting decisions for our github issues as well. Since github issues don't provide any forms to fill out certain attributes for an issue it was decided to document the decision criteria as a comment for each issue with the following attributes:

  • Motion: Exact wording of the motion which will be moved.
  • Change Type: describes the severity of the proposed change -> HL7 International categories (Any, None, Non-substantive, Compatible-substantive, Non-compatible)
  • (Ballot) Resolution: final resolution -> HL7 International (ballot) categories (Persuasive, Persuasive with Mod, ...)
  • Mover/Seconder: For-Against-Abstain:

Information if an issue is derived from a Ballot

Since github issues cannot be created automatically out of HL7 Austria Ballot results, it was decided to document the Ballot information as a comment for each relevant issue with the following attributes:

  • Ballot Info: from which ballot it came from

  • Ballot Weight: categories (and codes) from HL7 Austria ballots for a comment

    • NEG-S (negative, serious), NEG-G (negative, minor), Z-V (approval with proposal), Z-T (approval - typo), Z-F (approval with question), Z-K (approval with comment)

Support

We actively monitor the issues coming in through the GitHub repository at https://github.com/HL7Austria/HL7-AT-FHIR-Core-R4/issues. You are welcome to register your bugs and feature suggestions there. For questions and broader discussions, we use the TC-Austria channel on Zulip.

Footnotes

  1. country codes are ISO 3166-3 in the Alpha-2 code format, all lowercase. ↩ ↩2