Software Artifact Model
This guide gives an overview of the software artifact model which describes the relationship between artifacts used in software development.
Intended for
Software engineers.
Overview
The picture below visualizes the software artifact model.
Component capability
Component capabilities describe what the corresponding version of a component is capable of in its currently implemented state.
See the Component Capabilities Guideline for more details.
Detailed design
Detailed design is based on architecture documentation, along with feature descriptions and acceptance criteria. The design work includes a feature breakdown of user stories and tasks. The design is documented in the source code repository. This also holds for software development kit (SDK) documentation.
Modeling is done using an approved UML diagrams tool. Plant UML is recommended, but it is also allowed to use other tools.
Threat modeling is also a related but high-level activity.
Code
Implementation includes the following:
- Writing code on short-lived Git branches using the established collection of coding guidelines.
- Writing unit and component tests, see Unit test case and Component test cases.
Pull requests
When a task for updating documentation, test cases, or source code has been implemented, a pull request is created and linked to the task work item. This process is a crucial part of maintaining the integrity of the codebase, as it allows for thorough review and testing before the changes are integrated.
Note: If using Team Foundation Version Control (TFVC) instead of Git, pull requests correspond to check-ins and branches to shelve requests.
The completion of the pull request includes the following steps:
- Code and documentation review (done as part of the pull request completion). See the Code Review Guideline for further information.
- Execution of the pull request build job, which performs:
- Static code analysis, see the guide about Static Code Analysis for further details.
- Execution of automated tests (including regression tests).
- Check on code coverage.
- Generation of an HTML site using Doxygen.
- Build and publication of artifacts to be picked up by a release pipeline.
Unit test cases
A unit test is usually a box test of a separate class or function to verify its behavior. Automatic tests are developed for all code and executed as part of the pull request before the code is integrated.
Test cases shall be independent of the order of test case execution. Code coverage is measured during execution and compared with the defined minimum acceptable level.
Unit test cases are described (including steps and expected results) together with the test code, or in a test case, work items are linked to the test code. How to include the documentation depends on the framework and is included in the framework descriptions.
The test result will be analyzed in the data of the pull request execution (e.g. the pull request will not finish if there are failed tests).
The Unit Test Writing Guideline provides valuable tips to anyone involved in creating unit tests.
Component test cases
Component tests shall test the feature and user story acceptance criteria. These tests are mostly automated and executed in pipeline build jobs.
Like unit tests, component tests are documented with the test code or in a test-case work item linked to the test code.
The result of the component test execution can be analyzed in the build job output.
Manual test cases are rare in software unit and component tests. In cases where they are needed, they should be defined in test case work items and be part of a test suite in Azure DevOps (ADO). When the manual test cases are being performed, the execution of the test suite should be triggered so that the test result can be registered directly in ADO.