process: project planning overview

Introduce initial version of project planning.

Issue-ref: see #35

docs/platform_management_plan/project_management.rst

@@ -60,7 +60,7 @@ Steering of the project is done by two committees: *project lead circle* and *te
 
   Each *Project Lead* is allowed to nominate one *Technical Lead*. The *Technical Leads* form the "Technical Lead Circle". In case of absence, a technical lead can nominate a deputy. *Technical Leads* have the following responsibilities:
 
-  * Review and approval of *Contribution Requests*, which add or modify SCORE platform features.
+  * Review and approval of contributions, e.g. *Feature Requests*, which add or modify SCORE platform features.
   * Project management of the platform development, e.g., creation of the roadmap.
   * High-level project control and coordination between multiple software modules.
   * Escalation instance for software module project leads and committers.
@@ -89,8 +89,7 @@ Technical committees
   The planning of the activities is done by every *Community* independent of other
   teams. Each *Community* has a *Community Lead*, who is nominated by the *Technical lead circle*. The prioritization of some topics can be requested by the *Technical lead circle*
   in order to achieve milestones on time. All important architectural decisions
-  should be reported to the project as *Contribution Request*
-  to get the final approvement from the *Technical lead circle*.
+  should be reported to the project as *Feature Request* to get the final approvement from the *Technical lead circle*.
 
 * **Cross functional teams**
 
@@ -128,7 +127,7 @@ Meeting Structure
 
 * **Committer Circle Meeting**
 
-  Regular participants of the *Committer Circle meeting* are the *Committers* of the main *SCORE* project and of all software modules/child projects. The *Committer Circle Meeting* is lead by the *Technical Leads*. The main purpose of the meeting are in-depth technical discussions and evaluation of the *Contribution Requests*, that could not be approved in the *Technical Lead Circle meeting* and demand more technical discussions.
+  Regular participants of the *Committer Circle meeting* are the *Committers* of the main *SCORE* project and of all software modules/child projects. The *Committer Circle Meeting* is lead by the *Technical Leads*. The main purpose of the meeting are in-depth technical discussions and evaluation of contributions, e.g. *Feature Requests*, that could not be approved in the *Technical Lead Circle meeting* and demand more technical discussions.
 
   The *Committer Circle meetings* are announced via *[email protected]* mailing list and are open for everyone who is registered to this mailing list. All meetings are documented as *GitHub Discussions* in `Committer Circle section <https://github.com/orgs/eclipse-score/discussions/categories/committer-circle>`_ and can be read by everyone. Topics for the *Committer circle meetings* can be proposed only by regular participants and will be prioritized by the *Technical lead circle*. Proposals for agenda topics can be added as comment to the respective *GitHub Discussion* or sent to the *Technical lead circle Assistant*.
 
@@ -181,4 +180,214 @@ meetings, where such topics are discussed and decided, see `Steering committees`
 
 Planning
 ========
-coming soon
+
+Planning infrastructure
+------------------------
+`GitHub issues <https://github.com/features/issues>`_ are used to plan and to track
+work. To be able to find issues faster and to filter for them more efficiently,
+we use labels.
+
+Labels
+^^^^^^
+To facilitate the organization and tracking of tickets related to the same feature
+or topic, labels are utilized for issues and pull requests. Labels are a powerful
+feature that allows you to search and filter tickets based on specific labels, and
+you can save these filters in a *GitHub Project* view. However, it is important
+to exercise caution when creating labels to avoid confusion and ensure easy tracking.
+
+It's worth noting that labels are associated with a repository, not a *GitHub Project*.
+To create new labels in the repository requires special rights and only
+*project leads* and *committers* should have this capability.
+
+For the main *SCORE* repository, there exist already some predefined labels:
+
+* *feature_request* label is used to identify *PRs* and *GitHub Issues* that are part
+  of a *Feature request process*
+* *project_lead_circle*  label is used to identify *PRs* and *GitHub Issues* that are relevant
+  for *Project lead circle*
+* *tech_lead_circle*  label is used to identify *PRs* and *GitHub Issues* that are relevant
+  for *Technical lead circle*
+* *infrastructure*  label is used to identify *PRs* and *GitHub Issues* that are relevant
+  for *Tooling/Infrastructure Community*
+* *testing*  label is used to identify *PRs* and *GitHub Issues* that are relevant for
+  *Testing Community*
+* *software_architecture*  label is used to identify *PRs* and *GitHub Issues* that are relevant
+  for *Software Architecture community*
+* *software_development_process*  label is used to identify *PRs* and *GitHub Issues* that are
+  relevant for *Software Development Process Community*
+
+  .. image:: _assets/contribution_request_label.png
+     :width: 800
+     :alt: Infrastructure overview
+     :align: center
+
+Additionally, in the main *SCORE* repository there should exist a label for every
+software module.
+
+Every software module project, located in another repository, is free to define
+additionally its own labels. It is recommended to create labels at least
+for specific areas that may encompass multiple features.
+
+Types of tasks and structure
+------------------------------
+For better structuring of the tickets following *GitHub Issue* types are introduced
+in the main *SCORE* repository. It is recommended for all *child projects* to
+introduce the same types.
+
+.. image:: _assets/issue_types.png
+    :width: 600
+    :alt: Issue types overview
+    :align: center
+
+* *Saga* *GitHub Issue* of type *Saga* is the highest level hierarchy and can not
+  be a sub-issue of another ticket. If you want to group *Sagas* together, you will
+  need to use labels. *Saga* can have multiple *Epics* as sub-issues. In really
+  exceptional cases, also a *Story* can be a direct sub-issue of a *Saga* as well.
+* *Epic* *GitHub Issue* of type *Epic* groups multiple *Stories* together and is sub-issue
+  of exactly one *Saga*. *Epics* can be also standalone *GitHub Issues* without being
+  a child of any *Saga*. *Saga* should be the only way for grouping *Epics* together.
+  Grouping standalone *Epics* with labels is not something, what we encourage you to do.
+* *Story* *GitHub Issue* of type *Story* is the lowest planning granularity and represents
+  concrete task, that should be done, e.g. by a developer. Normally *Stories* are
+  grouped together in an Epic. In some cases a *Story* can exist as a standalone *GitHub issue*.
+  Grouping standalone *Stories* with labels is not something, what we encourage you to do.
+* *Bug* *GitHub Issue* of type *Bug* is used to report any kind of problems. It can be
+  a standalone *GitHub Issue* or can be a sub-issue of an *Epic* or a *Saga*.
+  It is also ok to use labels to group multiple *Bugs* that are related to the same topic.
+
+Main *SCORE* project defines templates for every type of *GitHub Issues*
+to ensure, that every ticket has all necessary information.
+
+For a better structuring of the *GitHub Issues*, we use a beta
+`sub-issue feature <https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/adding-sub-issues>`_,
+that should be officially released in the beginning of 2025.
+*Sub-issue feature* allows to create a "parent-child" relationship between *GitHub Issues*.
+That allows better structuring of the project and helps to keep *GitHub Issues*, that
+are related to the same topic, together.
+
+.. image:: _assets/sub_issues.png
+    :width: 600
+    :alt: Sub issues overview
+    :align: center
+
+
+Traceability
+^^^^^^^^^^^^
+To achieve a better traceability it is highly recommended to link all *PRs* to the corresponding
+*GitHub Issues*. If done properly, you will be able to see for every *GitHub Issue*
+all relevant source code changes. Normally *PRs* reference *GitHub issues* of type *Story*
+or of type *Bug*. How to link *PRs* to *GitHub Issues* is described in more details in this
+`guide <https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue>`_.
+
+.. image:: _assets/traceability.png
+    :width: 300
+    :alt: Traceability overview
+    :align: center
+
+GitHub Projects
+^^^^^^^^^^^^^^^
+*GitHub Projects* is a very powerful tool that allows creation of various views on
+the status of the project, helps to plan the work and to monitor the current progress.
+In particular, *GitHub Project* allows to extend *GitHub Issues* with following information:
+
+* objective
+* dependencies on other activities or information
+* responsible person
+* resources
+* mapping to work product
+* start, end, duration, effort
+
+Note: The information on start, end, duration, and effort may sometimes be complicated
+to estimate in the execution in an open source environment. Nevertheless, tasks
+should be planned as part of releases, which sets already an implicit
+duration and end date.
+
+Software module project leads shall also use *GitHub Project* for their planning. The overview of *GitHub Project* features can be found `here <https://docs.github.com/en/issues/planning-and-tracking-with-projects>`_.
+
+Multiple *GitHub projects* are defined in the main *SCORE* project:
+
+* a separate project for every community
+* a project for technical lead circle
+* a (GitHub) *roadmap project* with the overview of all upcoming features & releases.
+
+  As *GitHub Projects* are not restricted to one repository but
+  can include information from multiple repositories of the same organization,
+  *roadmap project* gives an overview of all *Sagas*, that are relevant for the roadmap,
+  including those ones in the software modules. Prerequisite for this is that project
+  leads of all software modules always assign their sagas to the *roadmap project*.
+  All sagas in the *roadmap project* are extended with additional information
+  as e.g. start date and due date, to keep the status of the project always transparent.
+  Additionally, the main *SCORE* repository defines project wide milestones & releases,
+  that are visible in the roadmap as well.
+
+.. image:: _assets/roadmap_example.png
+    :width: 600
+    :alt: Roadmap example
+    :align: center
+
+Releases and milestones
+^^^^^^^^^^^^^^^^^^^^^^^^
+GitHub allows to define various milestones & releases for every repository. The definition of the milestones and releases is proposed by the *Technical Leads* and is approved by *Project Leads*.
+
+In the main *SCORE* project we use milestones to mark important stages of the project and map sagas or in some cases also other *GitHub Issues* to them.
+
+*Releases* are used for structuring of the development activities. Exact scheme for the releases of the *SCORE* will be provided here later.
+
+You can find "up to date" overview of the release plan and milestones in the following section `Score Releases <https://eclipse-score.github.io/score/score_releases/index.html>`_.
+
+Planning process
+----------------
+Generally, every team is responsible for planning and managing of its backlog.
+For small improvements or clarifications, you can create *GitHub Issue* with a exhaustive
+description and map it to the topic using labels. For small improvements/bugs
+in the software modules you should create *GitHub Issues* directly in the repository
+of the submodule. The project leads and committers of the corresponding software module,
+circle or community will check the issue and in case they will accept it, they will
+take it over to one of their *GitHub Projects*. In case, the topic, that you raise in the issue has a big impact on the platform, you can be asked by the committers to raise a *Feature Request* and to do a POC in the `incubation repository <https://eclipse-score.github.io/score/features/integration/index.html#incubation-repositories>`_ .
+
+Contribution to the project is described in more details in `Contribution Request Guideline <https://eclipse-score.github.io/score/process/guidelines/contribution_request/index.html>`_.
+In general, everyone who wants to provide something new to the project, e.g. a new feature
+or a tool, should provide an exhaustive description, requirements and in some cases
+also initial draft of the architecture as part of the *Feature Request*.
+*Feature Requests* are regularly reviewed in the *Technical lead circle*
+and then get either accepted or declined.
+
+After the *Feature Request* was accepted, then the *Pull Request* with the
+*Feature Request* gets merged. The corresponding *GitHub Issue* gets a reference to the
+newly defined saga which plans the implementation of the feature request and afterwards *GitHub Issue* for *Feature Request* gets closed. The saga is at the beginning in the state *"Draft"*. Please be aware, that "status" of the tickets is modelled in *GitHub Project* as *GitHub Issues* do not provide the possibility to define additional states.
+
+The *Technical lead circle* is responsible for maintenance of the backlog with sagas,
+their prioritization and creation of the roadmap. Together with software module
+project leads and community leads in the "Committer circle" they go through the backlog, decide when and which saga should be implemented in which order and update the roadmap accordingly.
+
+As soon as the saga was planned for implementation, its state is changed to *"Open"*.
+As next step, a *GitHub Issue* of type *epic* is created as sub-issue of the saga
+and gets assigned to one of the *Communities* for refinement. The state of the saga changes from "Open" to "In Specification".
+
+.. image:: _assets/saga_status_workflow.svg
+    :width: 900
+    :alt: Planning workflow
+    :align: center
+
+The members of the *Responsible Community* define or refine feature, process or tool requirements. They may also create feature architecture and high level component requirements for every involved software component. Depending on the feature scope, one of the cross-functional team can be requested to make a POC in the `incubation repository <https://eclipse-score.github.io/score/features/integration/index.html#incubation-repositories>`_. Finally, *Responsible Community* does the break down of the corresponding *saga* to the tickets that can be assigned to the individual software modules or *communities*.
+As most of the software modules will have their own separate repository,
+then the detailed tracking of their work will also happen inside of that repository.
+However, the corresponding saga of the SCORE repository will still have a sub-issue of type epic,
+that will describe the work, that should be done inside of the software module for better planning.
+In the epic description there should be a link to the software module repository ticket,
+where the detailed information and break down to the stories can be found.
+For those communities or modules, that are part of the main *SCORE* repository,
+the break down to the stories should be done directly inside of the epic.
+
+As soon as the work on saga starts, its status is changed to "In Progress"
+and its sub-tickets get assigned to the project leads of the software modules
+or leads of the *communities*. During the development of the saga,
+we use "trunk based approach", it means, that we do not create any separate branches,
+but develop the software directly in the trunk/main using feature flag, that is marked as "experimental" at the beginning.
+
+The *Technical lead circle* regularly monitors the status of the sagas with the status
+"In Progress", resolves conflicts and updates the roadmap if necessary.
+
+As soon as the saga is implemented and fulfills to 100% our software development process requirements, the decision is taken in the *Technical lead circle* whether the feature should be
+officially available and in case of the positive decision, the feature flag status
+is changed from "experimental" to "official".