Providing design documentation with code changes

Term	Definition
SAD	Software Architecture Document - contains SDL (or ATF) functional and technical overview for newcomers and support engineers
Architecture	Set of High-level design solutions and approaches
SDD	Software Detail-design Document - describes SDL components design solutions
Doxygen	Documentation generator, a tool for writing software reference documentation

Overview

SDL and ATF are complex embedded systems, which provides cross- platform and cross- environment integration mechanisms. Specter of cross-platform, protocol, API and business functionality requires architectural and design specification for swift introduction.

Issues

1. Architectural and design solutions shall to be documented and easy maintained
2. SDL and ATF technical documentation shall be easy reviewed by SDL integrations for further SDL maintenance and update
3. Open-source contributors could deliver own design solutions

Changes input

• SDL Evolution change board
• Github SDL Core issue board
• Github ATF issue board

Solution

All OpenSDL and ATF changes need to be delivered in PR with up-to-date Architectural and Design documentation.

Procedure aspects

Each SDL and ATF functional and non-functional changes have to follow next steps:

1. Analisys Architectural changes (see checklist and help table)
   • Updating SDL SAD and/or [ATF SAD][atf_sad] source
   • Sending SAD update PR
2. Analisys SW Detail Design changes (see checklist and help table)
   • Create or update Component(s) SDD
   • Commit SDD changes
3. Source code implementation
4. Verify that changes from p.4 follow documentation from p.1 and p.2
   • Repeat p.1-2 according to final implementation
5. Send Pull Request with
   • link to SAD updates PR (if applicable)
   • Design document commit (if applicable)
   • Source code changes

Technical aspect

• Doc Down (extension of MarkDown) format is used for SAD documentation
  • It allows to automatically generate fancy documentation on the Ford Developers Portal.
• SAD source are being updated simultaneously with SDL Core source according to GitFlow
  • It's guaranty source and documentation consistence in master and release branches.
  • Note: One of the expected Ford portal features is showing Documentation by specific releases version.
• Doxygen format is used for SDD documentation
  • It allows to generate local stand-alone version of the all Detail-Design documentation with all interfaces and classes descriptions
  • The same Doxygen format will be used for documentation page on the Portal.
• SDD output contains following
  • Detail design according to SDD template: UML diagrams, SW patterns and approaches
  • Auto-generated Doxygen comments from the Component source files

Configuration aspects

SAD

• For end user SAD is available on the Ford Developers Portal.
• Source files in Doc Down format is open for enhancement by sending PRs to SDL Core guides repository.
  • Note: After sending PR you will be able to see you changes with temporary link to the Portal.

SDD

• For end user SDL Core and ATF SDDs can be generated from core source
  • cd ${SOURCE_REPOSITORY}
  • doxygen
  • chromium-browser docs/html/index.html
• Each SDL component need to have an own SDD document as following

/src/components/COMPONENT
	docs/FORD.OpenSDL.SDD.COMPONENT.dox
	src/...
	include/...
	...

• Each ATF component need to have an own SDD document as following

/module/COMPONENT
	docs/FORD.OpenATF.SDD.COMPONENT.dox
	file1.lua
	file2.lua
	...

• There is available SDD Template for OpenSDL and [ATF][atf_sdd_template], which contains chapters for most of possible design aspects and initial document version creation instruction.
  • Please, follow instructions at the top of SDD Templates

Pull request DoD

1. Link to SAD update (in case of CRQ or Feature implementation)
2. Commits with SDD update is provided (in case of CRQ and signification bug-fix)
3. Commits with source code according to COMMITTERS.md agreements

Appendices

Documentation update Checklist

• Do we affect Architecture?
  • Adding new functional component for SDL and/or [ATF][atf_sad_component]?
  • New global interface for inter-components communication?
  • Provides new high-level functionality for component?
  • New system state?
  • New cross-layer data type?
• Do we change Design?
  • Adding new internal interface or implementation?
  • Changed significant component sequence?
  • New Component data-type?

Issue-to-Documentation table

Following table shows design documentation changes in terms of Core changes:

Core \ Document change	SAD update required	SDD changes required	Source Code changes required
Feature	+	+	+
Change Request	-	+	+
Bug-fix	-	-	+

References:

• SDL Evolution change board
• SDL Core issues and questions
• SDL ATF issues and questions
• Ford developers portal
• SDL Core Software Architecture Document
• [ATF Software Architecture Document][atf_sad]
• Doc Down format specification
• Doxygen specification
• SDL Guides source repository
• SDL SDD template
• [ATF SDD template][atf_sdd_template]
• PRs check-list

comment: #[atf_sad]: https://smartdevicelink.com/en/guides/core/atf/table-of-contents/ comment: #[atf_sad_component]: https://smartdevicelink.com/en/guides/core/atf/components-view/ [atf_sad]: https://smartdevicelink.com/en/guides/pull_request/93dee199f30303b4b26ec9a852c1f5261ff0735d/atf/table-of-contents/ [atf_sad_component]: https://smartdevicelink.com/en/guides/pull_request/93dee199f30303b4b26ec9a852c1f5261ff0735d/atf/components-view/

comment: #[atf_sdd_template]: https://github.com/smartdevicelink/sdl_atf/blob/develop/docs/FORD.OpenATF.SDD.TPL.dox [atf_sdd_template]: https://github.com/pestOO/sdl_atf/blob/feature/SDD_template/docs/FORD.OpenATF.SDD.TPL.dox