docs: Add project proposal template

8cebe6c4 · Benjamin Engel · ccdb0222 · 8cebe6c4 · 8cebe6c4 · 8cebe6c4
--- a/.gitignore
+++ b/.gitignore
+*.code-workspace
+*concept_document/adoc/.asciidoctor/
+concept_document/adoc/generated_images/
+*.html
\ No newline at end of file
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
+# Cache docker images
+cache:
+  key: one-key-to-rule-them-all
+
+stages:
+  - build
+
+variables:
+  GIT_SUBMODULE_STRATEGY: normal
+
+html:
+  stage: build
+  tags:
+     - asciidoc
+  script: 
+    # touch the main build files to make sure last-updated is updated
+     - touch main.adoc
+
+    # Build the asciidoc documents into html
+     - asciidoctor -r asciidoctor-diagram main.adoc -o Project_Proposal.html
+  artifacts:
+    paths:
+     - Project_Proposal.html
--- a/.gitmodules
+++ b/.gitmodules
+[submodule "asciidoc-resources"]
+	path = asciidoc-resources
+	url = ../../asciidoc-resources.git
--- a/README.adoc
+++ b/README.adoc
+= Project Name
+
+
+== Compiled Master
+* https://code.asam.net/simulation/proposal/osi/-/jobs/artifacts/master/raw/<FILENAME>.html?job=html[Download the latest version]
+
+== How to contribute?
+
+
+== Repository Structure
+
+----
+├───images      # Any images contained in the document
+├───subchapters # subdirectory containing all subchapters (included via main.adoc)
+    ├───<SUBCHAPTER_NAME.adoc>
+    └───...
+└───main.adoc   # The main file for compilation
+----
+
+== Useful Links
+
+* https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[Quick guide to writing in AsciiDoctor]
+* https://code.asam.net/simulation/proposal/openlabel/wikis/home[Tutorial on the ASAM Code Project Workflow]
--- a/appendix/A-1.adoc
+++ b/appendix/A-1.adoc
+=== Appendix 1
+
+Text
\ No newline at end of file
--- a/asciidoc-resources @ 491d4018
+++ b/asciidoc-resources @ 491d4018
+Subproject commit 491d40182fa19b234e054f3dbd64c0ab9b2c3399
--- a/images/PLACE_IMAGES_HERE
+++ b/images/PLACE_IMAGES_HERE
--- a/images/timeline.mmd
+++ b/images/timeline.mmd
+gantt
+	title  Project Plan
+	dateFormat  YYYY-MM-DD
+        axisFormat  %b %Y 
+    section General
+        Rework of OSI documentation:   2020-08-01, 330d
+    section Performance & Packaging    
+        Encoding and Data Modeling: 2020-06-01,240d
+        Data Traffic Reduction: 2021-01-01,270d
+    section Sensor Modeling    
+        Extend OSI messages:    2020-06-01, 480d
+        Extension for EnvironmentalConditions:  2020-06-01,360d
+        Extension for SensorView & SensorViewConfiguration: 2021-04-01,120d
+        Create an interface for visualization:  2020-09-01,390d
+        Adapt/Extend the osi-validator: 2020-08-01,360d
+        OSI Alignment with ISO 23150:   2020-06-01,390d
+    section Traffic Participants & Infrastructure  
+        Allow for control of and simulator interface to TrafficParticipants:  2020-11-01,  270d
+        Enable V2X communication:   2021-04-01, 120d
+        Allow usage of OSI as a measurement file:  2020-06-01,300d
+        Extend OSI models:  2020-06-01,480d
+    section Harmonisation  
+        ID-Management:  2020-11-01,210d
+        Road specific map information:   2020-07-01 ,90d
+        Consistency with OpenDRIVE: 2020-06-01,120d
+        Analysis of OSI-NDS Workflow:  2021-01-01,60d
+    section Releases
+         V3.3.0 :crit, 2020-10-01,31d
+         V3.4.0 :crit, 2021-03-01,31d
+         V4.0.0 :crit, 2021-07-01,31d
+         V4.1.0 :crit, 2021-10-01,31d
\ No newline at end of file
--- a/images/timeline.svg
+++ b/images/timeline.svg
--- a/main.adoc
+++ b/main.adoc
+= Project Proposal
+include::preamble.adoc[]
+
+include::subchapters/1-1_executive_summary.adoc[]
+
+== Overview
+include::subchapters/1-2_motivation.adoc[]
+include::subchapters/1-3_use_cases.adoc[]
+include::subchapters/1-4_requirements.adoc[]
+include::subchapters/1-5_relations_to_other_standards_projects_or_organizations.adoc[]
+
+== Technical Content
+include::subchapters/2_technical-content.adoc[]
+
+== Project Resources
+include::subchapters/3-1_work_packages.adoc[]
+include::subchapters/3-2_company_commitments.adoc[]
+include::subchapters/3-3_resource_summary.adoc[]
+
+== Project Plan
+include::subchapters/3-4_timeline.adoc[]
+include::subchapters/3-5_deliverables.adoc[]
+include::subchapters/3-6_review_process.adoc[]
+    
+[appendix]
+== Additional Resources
+include::appendix/A-1.adoc[]
--- a/preamble.adoc
+++ b/preamble.adoc
+:revnumber: 1.0 
+:revdate: {docdate}
+:toc: left 
+:toclevels: 2
+:sectnums:
+// header & footer for html
+:asciidoc-resources: ./asciidoc-resources
+//
+ifdef::backend-html5[]
+:toc: left 
+:nofooter:
+// html themes
+:stylesdir: {asciidoc-resources}/themes/html
+:stylesheet: asam.css
+:linkcs:
+// header & footer for html
+:docinfodir: {asciidoc-resources}/themes/html
+:docinfo: shared,private
+endif::[]
\ No newline at end of file
--- a/subchapters/1-1_executive_summary.adoc
+++ b/subchapters/1-1_executive_summary.adoc
+
+[preface]
+== Executive Summary
+Provide a summary of chapters 1-3. Shall consist of two paragraphs or half page at most. The text may be used by ASAM for publishing the project, e.g. in newsletter articles or the web page.
\ No newline at end of file
--- a/subchapters/1-2_motivation.adoc
+++ b/subchapters/1-2_motivation.adoc
+
+=== Motivation
+
+Provide a general explanation for the motivation of the project proposal. This may include the description of the history that led to the proposal, general problems with current industry practices or existing standards, identified areas for improvement or economic constraints that require the solutions proposed for this project.
\ No newline at end of file
--- a/subchapters/1-3_use_cases.adoc
+++ b/subchapters/1-3_use_cases.adoc
+
+=== User Perspectives
+The perspectives used to describe the use cases & user stories.
+
+. User XX
+. User YY
+
+
+.User XX 
+[cols="1,3",caption='User {counter:u1}: ']
+|===
+a| *Who are they?*   
+a|   
+
+a| *How do they work?* 
+a| 
+
+a| *Goals*                       
+a|  
+|===
+
+
+=== Use Cases
+
+Use cases in the context of ASAM standards describe the external behavior of the standardized system, i.e. the interaction of the system with a user or with another system. The description of use cases is particularly useful for explaining the motivation for new standards, major version development projects or the addition of new features in minor version development projects.
+
+.Use Case Name
+[cols="1,5",caption='UC {counter:uc1}: ']
+|===
+|*Relevant Users* | User XX, User YY
+|*Description* |	Write a brief description for the use-case.
+|=== 
+
+
+
+
--- a/subchapters/1-4_requirements.adoc
+++ b/subchapters/1-4_requirements.adoc
+=== User Stories
+
+What is a user story:
+
+* Describes requirements for a software, a solution, a system
+* Written from the user‘s perspective
+* Explains reason for feature requirement
+* Basis for communication and further specification
+
+
+
+TIP: As an AV/ADAS developer company, I want to search, review and reuse scenarios built by other companies, because we rely on spezialized external suppliers for scenario data for our development activities.
+
+Do not specify the implementation or technical solution, just the requirement of the user:
+
+[red]#As an ADAS developer, I want to integrate external scenario data as Java library# 
+
+[green]#As an ADAS developer, I want to integrate external scenario data directly in my programming environment to avoid switching tools during work.#
+
+* Do not forget the reason/motivation.
+* Do not make the user story too large, e.g. by putting two requirements into one.
+
+[red]#As an ADAS developer, I want to integrate external scenario in my programming environment and immediately recognize it as external, so I am aware that this data can be overwritten at next import.#
+
+[green]#As an ADAS developer, I want to use scenario data.#
+
+*INVEST criteria*
+
+A user story needs to fulfil these criteria:
+
+Independent +
+Negotiable +
+Valuable +
+Estimatable +
+Small +
+Testable
+
+
+Format:
+
+* As a <user role>
+* I want to <do>, <have>, <use> something
+* because / in order to
+
+
--- a/subchapters/1-5_relations_to_other_standards_projects_or_organizations.adoc
+++ b/subchapters/1-5_relations_to_other_standards_projects_or_organizations.adoc
+
+=== Relations to Other Standards or Organizations
+
+
+[[backward-compatibility-to-earlier-releases]]
+==== Backward Compatibility to Earlier Releases
+For any project where further compatibility considerations are necessary (beyond the project type), please detail them here.
+
+[[references-to-other-standards]]
+==== References to Other Standards
+
--- a/subchapters/2_technical-content.adoc
+++ b/subchapters/2_technical-content.adoc
+
+Provide a detailed description, how the identified usecases, features or issues (as per preceding chapter) shall be solved or implemented through the proposed project. Descriptions shall include, if applicable:
+
+*	Components of a system, which shall be standardized
+*	Features or functionality of the standardized components
+*	Method of standardization
+*	Potentially donated IP from member companies
+*	Toplevel requirements to be considered for developing the standard
+*	Statements about backward compatibility towards earlier versions of the standard
+*	Improvements & benefits of the changes as compared to earlier releases of the standard
+*	Assumptions
+
+The technical content description shall be understandable for readers with an engineering background, but with no specific domain expertise. Consequently, a brief technical introduction may be needed.
+
+=== <Sub headers>...
--- a/subchapters/3-1_work_packages.adoc
+++ b/subchapters/3-1_work_packages.adoc
+=== Work Packages 
+A breakdown of the project into individual work packages and the corresponding effort required to complete them. Effort should be given in man-days.
+
+
+.Title
+[cols="1,5",caption='WP {counter:wp1}: ']
+|===
+| *Description* 
+| 
+
+| *Deliverable* 
+a|
+
+| *Effort (Man-days)* 
+| 
+|===
+
--- a/subchapters/3-2_company_commitments.adoc
+++ b/subchapters/3-2_company_commitments.adoc
+=== Company Commitments 
+Member companies contribute resources for the project as per the following table.
+
+.Commitments
+[%header,format=csv,frame=topbot,grid=rows]
+|===
+include::3-2_signups.csv[]
+|===
+
+Members of the CCB are project participants with the necessary permissions on the project repository to:
+
+. Push content to the protected project branches 
+. Accept merge requests from other project members
+
+.Change Control Board (CCB)
+[options="header",cols="45,45,10",frame=topbot,grid=rows]
+|===
+|Participant contact details (name, phone, email)| Company (Name, Location) 
+|||
+|===
+
+The following intellectual property will be transferred from member companies to ASAM:
+
+.Intellectual Property
+[options="header",cols="45,45,10",frame=topbot,grid=rows]
+|===
+|Company (Name, Location)    | IP Description | Value (Euros)
+|||
+|===
--- a/subchapters/3-2_signups.csv
+++ b/subchapters/3-2_signups.csv
+Company,Location,Commitment,Participant(s),Participant Email
\ No newline at end of file
--- a/subchapters/3-3_resource_summary.adoc
+++ b/subchapters/3-3_resource_summary.adoc
+
+
+=== Effort Summary
+
+
+.Required Effort (man-days)
+[%header,cols="2,3*>"]
+|===
+|*WP Category* | *Project Members* |*Service Provider* |*Total* 
+| Category name |  0 | 0 | 0
+
+| *Total* | *0*  | *0* | *0*
+|===
+
+
+.Resource Check
+[%header,cols="4*>"]
+|===
+|            | Project Members | Service Provider |Total
+|*Required*  | 0             | 0               | 0
+|*Committed* 3+| 0
+|===
+
+==== Budget
+[NOTE]
+--
+This section details the budget required by the project to e.g. pay service providers and the funds to be provided by ASAM. The limits are determined as a factor of the total required work effort. The corresponding effort is allocated a fixed price of 700 EURO per man-day.
+
+.Funding limits
+[cols="2,1"]
+|===
+|Project Type |	Factor	
+|New, major, minor or revision standard development project|	0.25	
+|Study project	|0.25	
+|Concept project|	0.75	
+|===
+--
+
+.Funds required for Service Providers
+[options="header",cols="3,1,1"]
+|===
+| Task Description 
+
+| Effort +
+[man-days] 
+
+| Cost +
+[€700 / day]
+
+
+| XX  | 0 | 0.000 EUR
+| *Total*  | 0 | 0.000 EUR
+|===
+
--- a/subchapters/3-4_timeline.adoc
+++ b/subchapters/3-4_timeline.adoc
+ifndef::imagesdir[]
+:imagesdir: ../images
+endif::[]
+
+=== Timeline
+The work packages shall be carried out as per the following time schedule:
+
+image::timeline.svg[]
\ No newline at end of file
--- a/subchapters/3-5_deliverables.adoc
+++ b/subchapters/3-5_deliverables.adoc
+
+=== Deliverables
+At the end of the project, the project group will hand over the following deliverables to ASAM:
+
+. XX
+. XX
\ No newline at end of file
--- a/subchapters/3-6_review_process.adoc
+++ b/subchapters/3-6_review_process.adoc
+
+=== Review Process
+The following quality assurance measures shall be carried out by the project:
+
+* [ ] Project member review
+* [ ] Public review
+* [ ] Reference implementation
\ No newline at end of file