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:
Below we detail the guidelines and requirements for each of the above.
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
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 firstname.lastname@example.org 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:
[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.
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.