From 953bab323cf40cbd8fdd2c86bea1c86065216872 Mon Sep 17 00:00:00 2001 From: Lars Bauhofer Date: Sat, 11 Jul 2026 16:54:22 +0200 Subject: [PATCH] docs: Roll out DR-002-Proc FEP process across contributor docs Implement the consequences of DR-002-Proc (FEP process) across the four affected documents: - feature_request.rst: rewritten as the living FEP Process Guide, superseding the old TL-circle review guideline. Defines roles (Author, Shepherd, Architecture Community), labels, the five process phases with tracking-issue lifecycle, and the FEP template. - change_management.rst: adds FEP routing for Feature and major Feature Modification CRs. - software_architecture_overview.rst: updates references from the old guideline to the FEP Process Guide. - project_management.rst: aligns the Feature Request definition with the FEP tracking issue (type Feature Request, allowed as a parent to child Task issues for implementation tracking). Assisted-by: Claude:claude-sonnet-5 --- .../contribution_request/feature_request.rst | 211 ++++++++++-------- .../contribute/contribution_request/index.rst | 2 + .../change_management.rst | 91 +++++++- .../project_management.rst | 8 +- .../software_architecture_overview.rst | 4 +- 5 files changed, 216 insertions(+), 100 deletions(-) diff --git a/docs/contribute/contribution_request/feature_request.rst b/docs/contribute/contribution_request/feature_request.rst index 5d7b1cc542e..15418764b46 100644 --- a/docs/contribute/contribution_request/feature_request.rst +++ b/docs/contribute/contribution_request/feature_request.rst @@ -13,124 +13,149 @@ # ******************************************************************************* -Feature Request Guideline -############################## +Feature & Enhancement Proposal (FEP) +##################################### .. document:: Feature Request Guideline :id: doc__feature_request_guideline :status: valid - :version: 1 + :version: 2 :safety: QM :security: NO :realizes: wp__training_path[version==1] -This Feature Request Guideline is a "How-To for Dummies" for proposing/contributing a new feature or changes to an existing feature. -This Guideline is based on or references following documents: +.. _feature_request_guideline: + +This guide describes the **Feature & Enhancement Proposal (FEP)**: part of S-CORE's change +process, and the Analyze step for *Feature* change requests and *Feature Modification* change +requests with major impact, for example changes affecting the platform or other Feature Teams +(see the :ref:`FEP Track ` section of the :ref:`Change Management Plan `). + +Component-level and single-Feature-Team changes continue through the standard Analyze step +described in the :ref:`Change Management Plan `. A Feature Team may still choose +to record such a change as a Decision Record if it wants a persisted rationale; that choice does +not by itself require a Shepherd or Final Comment Period, both of which are specific to the FEP +Track. -* :ref:`Contribution Guideline ` -* :ref:`Change Management Plan ` -* :need:`Feature Template ` +This guide is based on or references the following documents: -Creation of Feature Request +* :need:`FEP Decision Record (DR-002-Proc) `, which records the original + decision and its rationale +* :ref:`Change Management Plan `, which defines the underlying ISSUE/PR change + request infrastructure used by every FEP + +.. note:: + This guide describes how the FEP is currently practiced and may evolve as the Architecture + Community refines it. :need:`DR-002-Proc ` remains the frozen record + of what was originally decided; it is not updated when this guide evolves. + +Roles +================================ + +**Author** - the :need:`Contributor ` proposing the change. Responsible for +writing and maintaining the FEP, integrating feedback, and driving consensus. + +**Shepherd** - a :need:`Committer ` of the Architecture Community, not the author, +who guides the FEP to maturity and judges when it is ready for the Final Comment Period. Finding a +Shepherd is the author's responsibility. If no one is willing to shepherd a proposal, it does not +proceed. + +**Architecture Community** - all :need:`Committers ` of the Architecture Community +(architects and Feature Team leads) with standing to review FEPs. During the Final Comment Period, +every member is expected to either raise a substantive objection or approve, explicitly or by +silence. + +Labels ================================ -.. _feature_request_guideline: +``fep`` is applied to the FEP PR and its tracking Issue throughout the whole lifecycle, and is what +a board or filtered view is built on. -1. As the very first step, you will need to become an official contributor, as described in -`Actions to Ensure Proper Contribution `_ +``fep:needs-shepherd`` is applied to the tracking Issue while no Shepherd is confirmed, and removed +once one is. -2. Afterwards you will be able to create a GitHub Issue in the main `score repository `_ -and mark it +``fep:fcp`` is applied to the tracking Issue only while it is in its Final Comment Period, and +removed once the FCP closes. -* with label *feature_request* if you want to propose a new feature, or -* with label *feature_modification* if you want to propose changes to an existing feature, +A FEP that sees no activity for an extended period, most commonly while unshepherded or shepherded +but not yet ready for FCP, may be marked with the existing ``Stale`` label like any other inactive +issue. This does not reject the FEP; it signals that it has lost momentum and may be picked up again +later. -as described in the :ref:`Change Management Plan `. +The Process: Five Phases +================================ + +**Phase 0 - Idea Exploration** (informal, no status) + +Post the idea informally in the S-CORE architecture channel before writing anything formal. This +surfaces obvious problems early, finds prior related proposals, and identifies whether a Shepherd +might be willing to pick it up. Move to Phase 1 once you have a willing Shepherd. -Please put a short description of your *feature request* into the GitHub Issue description, so that -everyone can immediately understand, what the *feature request* is about. +**Phase 1 - Draft + Shepherd Shaping** (status: ``Draft - Needs Shepherd`` -> ``Draft - +Shepherded``) -The acceptance criteria for a feature request to be accepted are: +Open a PR with your FEP draft, using the FEP template below. At the same time, open a tracking Issue +of type *Feature Request*, labeled ``fep`` and ``fep:needs-shepherd``, set to status ``Draft - Needs +Shepherd``, and reference it in the FEP via the ``:tracking:`` field. The Issue links back to the +FEP PR, giving bidirectional traceability. -.. code-block:: markdown +Once a Shepherd is confirmed, remove the ``fep:needs-shepherd`` label, move the tracking Issue to +status ``Draft - Shepherded``, and update it to name the Shepherd. - - Feature Request is written according to the [Change Management](https://eclipse-score.github.io/score/main/process/process_areas/change_management/change_management_concept.html) & [Feature Request Template](https://eclipse-score.github.io/score/main/process/process_areas/change_management/guidance/change_management_feature_template.html) - - Feature requirements written according to the [Requirements Engineering](https://eclipse-score.github.io/score/main/process/process_areas/requirements_engineering/requirements_concept.html) - - If necessary: extend the stakeholder requirements written according to the [Requirements Engineering](https://eclipse-score.github.io/score/main/process/process_areas/requirements_engineering/requirements_concept.html) +Author and Shepherd iterate until the proposal is complete and well-argued. When the Shepherd judges +it ready, they propose entry into the Final Comment Period to the Architecture Community chair (or +proxy). The chair/proxy then formally announces the FCP across all channels, including Slack, moves +the tracking Issue to status ``Under Review``, and adds the ``fep:fcp`` label. +**Phase 2 - Final Comment Period (FCP)** (status: ``Under Review``) -Technical Leads review regularly all new incoming *feature requests* (GitHub Issues labeled as *feature_request* or *feature_modification*). -This happens normally on Monday in the `Technical Lead circle `_. -As soon as you've labeled your GitHub Issue with *feature request*/*feature_modification* label, -TLs will see the *feature request* and will add it to the special GitHub project, -`Feature Request GitHub Project `_. -Inside of this *Feature Request GitHub Project* additional states, as shown in the table below, -are used for a better tracking of the *feature requests*. -These states symbolize the status of the *feature request* and not the "GitHub" states of the issue, therefore we will further speak about -*feature request status*. The initial status of every *feature request* is set to "Draft". +The Architecture Community has 14 calendar days to engage. Objections must be substantive and +technical; the Shepherd distinguishes blocking from non-blocking feedback and can reset the FCP once +if a significant new issue requires a revised proposal. -====================== ==================== -FR status Description -====================== ==================== -**Draft** Feature Request is in the initial state -**In Progress** This is actively being worked on -**In Review** Feature Request should be reviewed by the technical leads -**Accepted** Feature Request was accepted -**Rejected** Feature request was rejected -**Changes Requested** Changes requested -**POC Needed** "Proof of concept" in incubation repository is needed -====================== ==================== +Silence is approval. FCP closes with no unresolved blocking objections, the FEP is accepted. FCP +closes with unresolved blocking objections, the FEP is rejected. Escalation may intervene in +exceptional cases but is not the default path. Either way, the ``fep:fcp`` label is removed from the +tracking Issue once FCP closes. -3. After you have created a GitHub Issue, next step would be to start working on the *feature request*. -First of all, change the status of *Feature Request* to "in Progress" state. -*Feature Requests*, that stay in the status "Draft" longer as 4 weeks, will be deleted. -Afterwards create a PR with your proposal in the `/docs/features `_ score repository. -There you will find currently existing features as subfolders. Please choose the one that fits your *feature request* the most or -create a new subfolder, if none of existing feature match your *feature request*. Please take care, that the PR follows the :need:`Feature Template `. -You should try to put as much information as possible, as a good exhaustive description is a prerequisite for *feature request* to be accepted. +**Phase 3 - Decision** (status: ``Accepted`` | ``Rejected`` | ``Withdrawn``) -It is important to understand, that *feature request* consists of an GitHub Issue, that is used to track organizational information and -PR, that contains the technical content. This is explained once again in detailed in the :ref:`Change Management Worlflow ` -chapter of :ref:`Change Management Plan ` document. GitHub Issue always stays assigned to the owner of the *feature request*. -*Feature Request* PR will always be assigned to the owner of the *feature request* as well, but will additionally get the list of reviewers, that -should review this *feature request* PR. +If the FCP closed cleanly, the FEP PR is merged and recorded as a Decision Record. If the FCP closed +with unresolved blocking objections, the FEP is rejected. The author may withdraw at any point +before acceptance. In each case, the tracking Issue's status is updated to match: ``Accepted``, +``Rejected``, or ``Withdrawn``. +Breaking Change FEPs additionally require explicit approval from a minimum quorum of Architecture +Community members; they cannot pass by silence alone. -Review of Feature Request +**Phase 4 - Implementation Tracking** (status: ``Implementing`` -> ``Implemented``) + +The tracking Issue opened in Phase 1 stays open, moves to status ``Implementing``, and becomes the +implementation tracking artifact; it can carry child Task issues for the implementing teams via +GitHub's sub-issue feature. It is closed only when the implementation, not the FEP, is merged, at +which point it moves to status ``Implemented`` before closing. If implementation reveals the +accepted design is materially wrong, file a follow-up FEP rather than diverging silently. + +FEP Template ================================ -* As soon as you're done with description of your *feature request*, please put the status into "Ready for Review" so that Technical Leads know, - that they can start with the process of reviewing the *feature request*. Technical Leads will first do a short review of your *feature request*: - - * In case the impact of your *feature request* is trivial, then TLs can process your *feature request* immediately. - * Normally, TL circle will put the lead of the appropriate *FT* or *Community* as reviewer to the corresponding PR of the *feature request* for better analysis. - The CTF/Community lead will change the status of the *feature request* issue to "in Review" as soon as they will start reviewing your *feature request*. - The review can be delegated to any other participants of the FT or Community. - - * In case *feature request* can not be clearly assigned to any already existing team, Technical Lead circle will pick at least two suitable candidates - from the project to review the *feature request* PR. In that case, *feature request* should be reviewed by all reviewers. - - * In case of big architectural impact, Technical Lead circle can additionally decide to request a review for *feature request* PR from software architecture community. - -* After the review is done, the TL circle will set the status of the *feature request* accordingly and will - also put all further necessary information as GitHub Issue comments. The outcome of the review could be like following: - - * **Accepted** - You *feature request* is accepted. The *feature request* GitHub Issue should contain now a link to a new GitHub issue of type 'Epic', - that was created by Technical Leads, where detailed information regarding your feature is documented. - The epic should be also already assigned to the corresponding team (FT/Community). - If none of the FTs/Communities match the new *feature request*, then a new FT/Community will be founded. - You will be invited to the FT/Community for break down of the *feature request* and planning. - You can now merge the *feature request* PR and close the *feature request* issue. - * **Rejected** - You *feature request* was rejected. It could be either because your description was - not mature enough or because the proposal technically doesn't fit into S-CORE roadmap or architecture. - You will be able to find the summary of the review in the corresponding *feature request* issue comments. - The review comments will be done directly in the *feature request* PR. - * **Changes Requested** - We like your idea, but we would like to request some modifications. - This could be rather technical topics or also syntax issues in the description. - You will be able to find the summary of the review in the corresponding *feature request* issue comments. - The review comments will be done directly in the *feature request* PR. - * **POC needed** - We generally like your idea, but we don't have enough technical understanding of the *feature request*, - e.g. technical scope is too big, and we need a POC to be able to understand better, - how the proposed *feature request* fits into the overall solution. You will find in the GitHub issue comments - the decsription for both the scope of the PoC and the requirements and the acceptance criteria for the requested PoC. - Also, a so called *incubation repository* will be created by the reviewers of the *feature request*, where you should implement your POC. - Please be aware, that POC is not a guarantee, that you *feature request* will be accepted. + +FEPs use the same ``dec_rec`` need type as any other Decision Record (see the `Decision Record +Template`_). + +.. _Decision Record Template: https://eclipse-score.github.io/process_description/main/folder_templates/platform/docs/change/decision_record.html + +``:tracking:`` field is the one FEP-specific addition, linking the FEP to its tracking Issue from +Phase 1. + +Breaking Change FEPs - Additional Requirements +================================================ + +A proposal classified as **Breaking Change** must additionally include: + +* **Impact Inventory**: explicit list of known integrators, configurations, or customer deliverables + that will break +* **Migration Path**: concrete steps integrators must take, with estimated effort +* **Deprecation Timeline**: if a grace period is offered, how long and how the old behavior is + signaled as deprecated +* **Sign-off from Affected Teams**: acknowledgment, not necessarily approval, from leads of teams + known to be directly affected before FCP entry diff --git a/docs/contribute/contribution_request/index.rst b/docs/contribute/contribution_request/index.rst index 150f7d181f9..bb868771c5c 100644 --- a/docs/contribute/contribution_request/index.rst +++ b/docs/contribute/contribution_request/index.rst @@ -36,6 +36,8 @@ Feature Requests: Our Shared Roadmap Feature requests are at the heart of our evolution. They describe the intended functionality of the S-CORE platform and serve as a collaborative starting point where maintainers and contributors align on new ideas. These requests not only define the motivation and requirements but also shape the technical roadmap for future developments. We invite you to check out all current feature requests on our `Feature Request Board `_. +New Feature and major Feature Modification requests go through a :need:`Feature Enhancement Proposal (FEP) `, where an Architecture Community Shepherd guides the proposal to a Final Comment Period before it's decided. Component-level and single-Feature-Team changes are handled directly by the responsible team, as described in the :need:`doc__platform_change_management_plan`. + From Vision to Reality: Calling for Contributions ------------------------------------------------- diff --git a/docs/platform_management_plan/change_management.rst b/docs/platform_management_plan/change_management.rst index 517d3bccb10..e52463670bd 100644 --- a/docs/platform_management_plan/change_management.rst +++ b/docs/platform_management_plan/change_management.rst @@ -15,7 +15,7 @@ .. document:: Change Management Plan :id: doc__platform_change_management_plan :status: valid - :version: 1 + :version: 2 :safety: ASIL_B :security: YES :tags: platform_management @@ -135,6 +135,90 @@ Change Request Traceability Impact Analysis requires the following tools: :need:`[[title]] ` + +.. _fep_track: + +The FEP Track +^^^^^^^^^^^^^ + +Change Requests generally follow the four-step +:ref:`Change Request Workflow ` below. For most changes, **Analyze** means a +:need:`Committer ` reviews the ISSUE/PR and documents the accept/reject decision +directly there. + +Some changes carry enough governance weight that the decision is worth persisting, and the +community needs a structured way to reach agreement before implementation starts, rather than +relying on a single Committer's review. For these, **Analyze** is specialized into the **FEP +Track**: a Shepherd sponsors the proposal, a time-boxed Final Comment Period +(silence-as-approval) fosters quick decision making instead of open-ended review, and the outcome +is recorded as a Decision Record rather than only documented in the ISSUE. Create, Implement, and +Close are unaffected; only the Analyze step changes shape. See the +:ref:`Feature & Enhancement Proposal (FEP) ` for the full mechanics +(roles, phases, template). + +Today, the following Change Requests are routed onto this track: + +**Feature** change requests always go through the FEP Track. + +**Feature Modification** change requests go through the FEP Track when the change has major +impact, e.g. affecting the platform or other Feature Teams. Feature Teams retain authority over +modifications limited to their own domain. + +A clean, exhaustive definition of "major impact" is not achievable up front; see the `Key +Concept`_ in ``process_description`` for the baseline definition of a change. Classifying a Feature +Modification as "major" within that baseline is a judgment call made by the responsible +:need:`Committer ` at the time the change is proposed, including changes proposed +directly as a PR without a prior FEP. A change can be waived from the FEP Track by community +agreement if it is judged not to warrant it, or pulled into the FEP Track after the fact if a +:need:`Committer ` judges it major. + +.. _Key Concept: https://eclipse-score.github.io/process_description/main/process_areas/change_management/change_management_concept.html#key-concept + +**Component** and **Component Modification** change requests go through the standard Analyze step; +they are not routed onto the FEP Track, so neither a Shepherd nor a Final Comment Period is +required. The responsible team may still choose to record the change as a Decision Record for a +persisted rationale — that choice does not by itself trigger the FEP Track, since a Shepherd and +Final Comment Period are specific to Feature and major Feature Modification CRs. Either way, an +ISSUE is required; the only open question is whether the substantive discussion is captured +directly in the ISSUE or in a Decision Record referenced from it. + +The FEP mechanism itself is not inherently tied to CR type; Feature and major Feature Modification +are its first applied case. Extending the FEP Track to other CR types would be a separate decision, +not implied by this document. + +FEP tracking-Issue statuses are a refinement of the generic Change Status mapping described below +under Change Request Attributes, not a competing one: + +.. list-table:: FEP Status Mapping + :header-rows: 1 + :widths: 30,20,50 + + * - FEP tracking Issue status + - Generic Change status + - Notes + * - ``Draft - Needs Shepherd`` + - open + - Refines "open": PR exists, no Shepherd confirmed yet. + * - ``Draft - Shepherded`` + - open + - Refines "open": Shepherd confirmed, proposal being shaped. + * - ``Under Review`` + - in review + - The Final Comment Period. + * - ``Accepted`` + - in implementation + - FEP merged and recorded as a Decision Record. + * - ``Rejected`` / ``Withdrawn`` + - rejected + - FCP closed with unresolved objections, or the author withdrew. + * - ``Implementing`` + - in implementation + - Tracking issue stays open; may carry child Task issues. + * - ``Implemented`` + - closed + - Implementation merged; tracking issue closes. + + Change Request Attributes ^^^^^^^^^^^^^^^^^^^^^^^^^ :need:`gd_req__change_attr_uid` are implemented as follows: @@ -271,6 +355,11 @@ review results are resolved by the :need:`Contributor `. The re are documented in the ISSUE and/or linked PR. As long as the information is not sufficient, the related ISSUE is kept in status ``Open`` and Projects status ``Todo``, means ``in review``. +For Change Requests routed onto the :ref:`FEP Track `, this step is performed as +described in the :ref:`FEP Guide ` instead: a Shepherd, not a +single Committer, guides the analysis, and review ends in the time-boxed Final Comment Period +rather than in an open-ended ``in review`` state. + If the information is sufficient and it is decided to implement the change request, the ISSUE status is kept ``Open`` and the Projects status is set to ``In Progress``. diff --git a/docs/platform_management_plan/project_management.rst b/docs/platform_management_plan/project_management.rst index 23d54adf388..0080185828b 100644 --- a/docs/platform_management_plan/project_management.rst +++ b/docs/platform_management_plan/project_management.rst @@ -104,7 +104,7 @@ Steering of the project is done with the help of *Lead Circles*. - **-----------** - **-----------------------** * - - Decisions about strategical topics - - Review and approval of contributions, e.g. Feature Requests, which add or modify features + - Triage of incoming Feature Requests, routing platform-level and cross-Feature-Team requests to the FEP Track - Project Management - High-level project control and coordination between multiple software modules. - Deciding of adding / removing Repositories @@ -514,7 +514,6 @@ Each *Feature Team* has one *Lead* to organize the Team`s work. - `ORCSLC`_ - `ORCBKL`_ - | https://github.com/eclipse-score/orchestrator - * - .. _pmp_pm_per: **PER** @@ -676,8 +675,9 @@ Architectural Issues A *Feature Request* represents an independent work package used to describe and track a high-level request for the project. *Feature Request* work packages can be linked to -other work packages, but they must not be treated as parent work packages. *Feature Request* covers new Features as well as significant modifications of existing Features. -They are in the responsibility of the :ref:`Architecture Community `, shall aligned with :ref:`Project / Technical Lead Circle ` and the issues are part of the :ref:`Root Repository `. +other work packages, including as a parent to child Task issues used for implementation tracking once a FEP is accepted. *Feature Request* covers new Features as well as significant modifications of existing Features. + +Feature Requests are governed by the FEP Track (see the :ref:`Feature & Enhancement Proposal (FEP) `): the :ref:`Architecture Community ` owns the review via a Shepherd and Final Comment Period. The :ref:`Project / Technical Lead Circle ` triages incoming requests and is notified once a FEP enters its Final Comment Period, for roadmap awareness. Feature Requests are part of the :ref:`Root Repository `. `About Features `_ diff --git a/docs/users_guide/project_basics/software_architecture_overview.rst b/docs/users_guide/project_basics/software_architecture_overview.rst index e970bb4d642..ddf84bdaf97 100644 --- a/docs/users_guide/project_basics/software_architecture_overview.rst +++ b/docs/users_guide/project_basics/software_architecture_overview.rst @@ -27,11 +27,11 @@ Please note that the Eclipse S-CORE´s software architecture is continuously ref Eclipse S-CORE has a `software architecture community `_ **responsible for maintaining and evolving the architecture**. -By creating a **feature request**, structural changes as well as new functionality can be **proposed at any time**. +Structural changes and new functionality are proposed through a **FEP**. All **past feature requests** are documented in the corresponding `Feature Requests / Modification `_ GitHub project. -The **process for submitting a feature request** is described in the :ref:`contribution guide `. +**Submitting a FEP** is described in the :ref:`Feature & Enhancement Proposal (FEP) `. Participation in the architecture process is encouraged. The **software architecture community regularly organizes workshops** where contributors can: