Site Tools


participating:contributing:requirements

Requirements for delivery of software to 4S

This page is part of the 4S pages on contributing changes and describes the requirements for a delivery of software to 4S.

A deliverable of software to 4S consists of:

  • Full source code for the bug fixes or solution.
  • Documentation
  • Test reports

Below we detail the guidelines and requirements for each of the above.

Requirements for delivery of source code

This section covers the conditions for delivering source code to 4S. For how to actually submit your changes to the 4S source code repositories please see the page on submission of changes.

In order to have a system that is usable by the different teams and individuals working with 4S code we have set up some rules that needs to be followed. Notice that depending on the TRL of your system or component the rigidity with which we enforce this rules will vary - see the page about approval of submitted changes. If you have suggestions to changes or additions, then we would be happy to listen to you - the place for such discussions are in the Jira issue where these rules originally formed: JIR-17.

Source code delivered to 4S must fulfil the following conditions

  1. License:
    1. For new modules source code license should be clearly stated, and if you use anything but the default license you need to have this pre-approved by 4S. For further regarding 4S policies on licenses and intellectual property rights see our page on License and Intellectual Properties.
  2. Build:
    1. If changes are made to the build system, that requires configuration changes on the machines used for building, then the guides found here and the relevant parts of the general documentation (for instance "Guide til Viderudvikling") must be updated (*after* your Jira issue where you described the changes, and reasons for them have been triaged and accepted as something we want to do). Note: After your change, the wiki should still contain information on how to setup and build older versions of the software.
    2. If changes are made to how the software is built, then you need to update the relevant build instructions and relevant parts of the general documentation (the same extras as in the above are also valid here - e.g. there should still be instructions on the wiki on how to build old versions of the software, and you are not allowed to commit changes to the build system, until the Jira issue is accepted).
  3. Migration
    1. If changes influence database(s) or other persistent storage, then there must be migration plans, descriptions, tools, or other things made, so a running system can be (automatically) upgraded to the latest software without data loss.
  4. Documentation:
    1. If a source change influences the documentation, then the documentation must also be updated.
    2. The language for documentation of 4S components is English. This is both for external documentation and documentation inline in the source code.
    3. Please see further regarding requirements for documentation here.
  5. Version control and issue tracking:
    1. Every commit landing on a 4S source code repository must begin with the Jira issue tracking number(s) of the related Jira report(s). E.g.: “OT-70” in this commit message: “OT-70 Allowing user to login without having any patients or patient groups assigned.”. There can be multiple commits with the same tracking number if relevant or a single commit with several tracking numbers as long as the issues are related and linked in Jira. Issues should only be linked if they are truly related – like for example a task / subtask relationship – not just for the convenience of being able to commit multiple issues in one commit.
  6. Test:
    1. The documentation delivered with the source code must describe how the different types of test are run.
    2. A clean run of the tests (automatic and/or manual) included with the component must be performed and documented in the Jira report which corresponds to the commit before a pull-request can be done.
    3. Any new feature must either be covered by an existing test case or by a new one - where a test case is one or more automated test cases and/or a description of a manual test.
    4. See further regarding requirements for test here.
  7. Pull request:
    1. Source code is submitted using a pull request to the relevant Bitbucket repository/repositories
    2. It is the responsibility of the person accepting the pull request to verify that the above requirements are fulfilled, if the above requirements are not fulfilled then the pull request will be rejected, and a comment in Jira is made as to why it was rejected.
    3. If the above process is not followed, it is the responsibility of the person who accepted and merged the pull request to fix the issue. This can be done either by making a new commit, reverting the original, or by fixing it (run the missing tests, update the documentation etc.). Failing to comply with this can result in loosing write access to the repository.

Requirements for documentation

This section covers the requirements for documentation of systems and components in 4S. Notice that depending on the TRL of your system or component the rigidity with which we enforce the requirements will vary - see the page about approval of submitted changes. For how to actually submit documentation to 4S please see Submission of changes

The language for documentation in 4S is English. This is both for external documentation and documentation in the source code.

Documentation can be supplied in a number of formats, most typically either directly on the 4S wiki or as Word documents along with corresponding PDFs. The important thing is that versions of the documentation are tracked and that you can tell which version of the documentation corresponds to which of the source code.

Notice that in the OpenTele project large parts of the documentation for versions 1 and 2 are currently in Danish. In general, we require new OpenTele components, services or other larger additions to be documented in English, but if you are developing something like this please contact us so that we can have a dialogue about how/where/if to update existing documentation in Danish. Also we would like to have the existing Danish OpenTele documentation translated into English. So, please contact us at software@4s-online.dk if you would like to help us translate it.

Types of documents that can - but depending on type of change, do not have to - be part of the documentation that you should deliver:

  • Documentation overview
  • Overall system/component description
  • Design and architecture description
  • Installation and deployment guide
  • Operations guide
  • Developers guide
  • Communication and API documentation
  • User Interface documentation (where relevant)
  • Test guide
  • Test reports
  • Risk assessment (depending on consequences of the proposed change in terms of Medical Device classification, see [TODO: link to 4S page about handling Medical Device classification and risk assessment])

[TODO: short description of each of the documents above]

How much of and which documents you need to supply or change depends totally on the type of change you are doing. For instance, if you are contributing a simple bug fix that doesn’t change any module or communication interfaces or essential business behaviour (which a bug fix shouldn’t in any case) the Jira issue summarizing and explaining the bug will make up the core documentation of this change. Potentially you will also have added and run a (regression) test case for the bug and you should then explicitly state this in the Jira for the bug. If you are changing the communication interface and/or some basic behaviour of a component you will definitely have to change the component description, you may need to change details in an overall system design and architecture description, and you will need to change the communication and API documentation relating to the component. Any changes to build tools (new version or other) and build configuration should be reflected in the developers guide. And so on. The general rule is you supply and/or change the documents that are relevant in relation to the change that you are submitting. If you are submitting an entirely new system, as in an entirely new set of interacting components that make up a meaningful whole, you should supply all of the documents listed above. An example of a “system” under 4S governance is OpenTele. Examples of components in OpenTele v2.x.x could be the OpenTele citizen server or the KIH AuditLog.

Tests and reporting on tests

When you deliver code for a 4S component we require you to document the tests that you have performed before delivering the source code to our repositories. Notice that depending on the TRL of your system or component the rigidity with which we enforce the requirements will vary - see the page about approval of submitted changes. If you include new test cases please relate them to a use case describing a functional requirement or to a non-functional requirement.

We expect a typical 4S component to at least include unit and integration tests. Unit tests for verifying that a single interface, class or method works correctly and integration tests for verifying that a deployed component works and interacts as expected with regards to surrounding components and systems. Depending on the type of component and its functional and non-functional requirements you should also include results of any other types of tests – like performance or reliability testing - that you have performed before delivery.

participating/contributing/requirements.txt · Last modified: 2018/12/12 13:31 (external edit)