Skip to content

docs: Roll out DR-002-Proc FEP process across contributor docs #3076

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
qor-lb wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: Roll out DR-002-Proc FEP process across contributor docs #3076

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
211 changes: 118 additions & 93 deletions docs/contribute/contribution_request/feature_request.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Comment thread
masc2023 marked this conversation as resolved.
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 <fep_track>` section of the :ref:`Change Management Plan <change_mgmt_plan>`).

Component-level and single-Feature-Team changes continue through the standard Analyze step
described in the :ref:`Change Management Plan <change_mgmt_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 <contribute_contribution_guideline>`
* :ref:`Change Management Plan <change_mgmt_plan>`
* :need:`Feature Template <gd_temp__change_feature_request>`
This guide is based on or references the following documents:

Creation of Feature Request
* :need:`FEP Decision Record (DR-002-Proc) <dec_rec__proc__fep_process>`, which records the original
decision and its rationale
* :ref:`Change Management Plan <change_mgmt_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 <dec_rec__proc__fep_process>` remains the frozen record
of what was originally decided; it is not updated when this guide evolves.

Roles
================================

**Author** - the :need:`Contributor <rl__contributor>` proposing the change. Responsible for
writing and maintaining the FEP, integrating feedback, and driving consensus.

**Shepherd** - a :need:`Committer <rl__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 <rl__committer>` 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 <https://eclipse-score.github.io/score/main/contribute/general/contribution_attribution.html#contribution-attribution>`_
``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 <https://github.com/eclipse-score>`_
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 <change_mgmt_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 <https://github.com/orgs/eclipse-score/discussions/104>`_.
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 <https://github.com/orgs/eclipse-score/projects/4>`_.
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 <https://github.com/eclipse-score/score/tree/main/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 <gd_temp__change_feature_request>`.
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 <change_mgmt_workflow>`
chapter of :ref:`Change Management Plan <change_mgmt_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
2 changes: 2 additions & 0 deletions docs/contribute/contribution_request/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <https://github.com/orgs/eclipse-score/projects/4>`_.

New Feature and major Feature Modification requests go through a :need:`Feature Enhancement Proposal (FEP) <doc__feature_request_guideline>`, 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
-------------------------------------------------

Expand Down
Loading
Loading