Skip to content

Clarify required sections of the project proposal template #2810

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
wants to merge 1 commit into
base: main
Choose a base branch
from
+8 −6
Open

Clarify required sections of the project proposal template #2810

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
6 changes: 4 additions & 2 deletions project-management.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,12 +24,14 @@ At minimum, projects require the following resources to be successful:
These two sponsors should be from different companies.
* A group of designers and subject matter experts, dedicating a significant amount of their work time to the project. These participants are needed to design the spec, write a set of OTEPs, and create multiple prototypes. This group needs to meet with each other (and with their sponsors) on a regular basis to develop a successful set of proposals.

To propose a project, a**project document** must be created using the [project proposal template](project-template.md) as a guide. This document will be used as the initial proposal for the project.
To propose a project, a **project document** must be created using the [project proposal template](project-template.md) as a guide. This document will be used as the initial proposal for the project. With the exception of sections labeled as "Optional" or "Post-Approval", all sections of the template must be filled out.

A project proposal can then be submitted by placing the project document in the [projects](projects/) folder and making a pull request against the community repo.

As the project progresses, the project document should be kept up to date, and the community [README](README.md) should be updated to include any new project meeting information (see [contributing guide](https://github.com/open-telemetry/community/blob/main/CONTRIBUTING.md#updating-sig-information-on-the-readmemd)).

The project template may be updated and new or existing sections may become required for new projects. Existing projects are not required to update their project documents to the latest template.

Project leads are encouraged to define timelines for any work which will require public review, and to provide updates to the community in the form of [GitHub Project updates](https://docs.github.com/en/issues/planning-and-tracking-with-projects/learning-about-projects/sharing-project-updates). We have found that having scoped deliverables leads to an increased cadence in project work, and helps resolve debate. Timelines also help with getting a more coherent public review, as they allow the review community to plan on making themselves available. If timelines prove to be unrealistic, they can be always be updated.

## Project Lifecycle
Expand All @@ -46,4 +48,4 @@ The project lifecycle is as follows:
* **_On Track_**: The project is making progress, and leads consider the timelines currently defined in the project document achievable with the current resources. Updates may contain information about recent achievements on the project.
* **_At Risk_**: The project is at risk of not meeting its currently defined timelines. Leads and their GC liaison should discuss actions to bring the project back on track, which may include extending previously agreed timelines or re-scoping deliverables.
* **_Off Track_**: The project does not have the necessary resources to continue to meet the desired deliverables in a timeline manner, or participation is too low to continue. Leads and their GC liaison should address the level of interest and commitment from the community to re-scope deliverables and timelines, and consider closing the project if not satisfactory, removing the project document from the list of active projects and cancelling meetings and other logistics (e.g. GitHub teams).
* **_Completed_**: The project is complete. The project document is moved to the [completed projects](projects/completed-projects/) folder, meetings and other logistics are cancelled, and the corresponding GitHub project is closed.
* **_Completed_**: The project is complete. The project document is moved to the [completed projects](projects/completed-projects/) folder, meetings and other logistics are cancelled, and the corresponding GitHub project is closed.
8 changes: 4 additions & 4 deletions project-template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ In general, OTEPs are not accepted unless they come with working prototypes avai

Who is currently planning to work on the project? If a project requires specialized domain expertise, please list it here. If a project is missing a critical mass of people in order to begin work, please clarify.

### Industry outreach
### Industry outreach (Optional)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we add these as markdown comments underneath the title?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you mean in addition to adding it to the title or instead of adding it to the title?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I still struggle with making this optional, I would rather like to see a structured process like:

  • before start of the project, list who is aware already and who should be aware
  • (optional) list whom you have reached out to so far/whom you plan to reach out to before the project starts
  • (post approval, mandatory) work with SIG communications to make an announcement of the project via blog and social media

cc @open-telemetry/docs-approvers

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I still struggle with making this optional, I would rather like to see a structured process like:

I agree with you, but I would rather have this discussion in a separate PR. As it stands today, this is optional based on GC discussion. We can change that, but this PR tries to solve the previous problem: clarifying which parts are required and clarifying the relationship between the project management doc (which seems to be authoritative) and the template (which does not seem to be authoritative)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree with @svrnm's comments, I wouldn't make this optional, we should just clarify what's required

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I mean, the reality is that this is optional today, right? We can change it, but I just want to reflect the reality today

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree with @mx-psi.

I'd love to reignite the discussion about what we are expected to do as leaders of the project in ensuring that our community is not only accepting new contributors, but actively seeks to hear the voices of those who are known in the space where new projects are being proposed, which is what the current wording attempts to convey.

But the reality is that, today, we are not required to do this when proposing a new project. We assume people know about this new project because we believe we are big enough for people to follow closely what we are doing, and they'll naturally join. This PR marking this field as optional reflects this reality.


Who (people, companies) in the industry should be aware of this effort? Was there an attempt to get them onboard? What did they say?

Expand All @@ -39,11 +39,11 @@ Projects cannot be started until the following participants have been identified

What is the expected timeline the project will aim to adhere to, and what resources and deliverables will be needed for each portion of the timeline? If the project has not been started, please describe this timeline in relative terms (one month in, two weeks later, etc). If a project has started, please include actual dates.

## Labels
## Labels (Optional)

Issues should be properly labeled to indicate what parts of the specification it is focused on. List here the labels applicable to this project, and consider adding them to corresponding GitHub Project automation to include them automatically into the project backlog.

## GitHub Project
## GitHub Project (Post-Approval)

Once approved, a project should be managed using a GitHub project board (see [open projects](https://github.com/open-telemetry/community/projects?query=is%3Aopen)). This project board should be pre-populated with issues that cover all known deliverables, organized by timeline milestones.

Expand All @@ -59,7 +59,7 @@ See [project management](project-management.md#project-lifecycle) for more infor

Once created, please add a link to the project board here.

## SIG Meetings and Other Info
## SIG Meetings and Other Info (Post-Approval)

Once a project is started, its corresponding SIG should meet regularly for discussion. These meeting times should be posted on the [OpenTelemetry public calendar](https://github.com/open-telemetry/community#calendar) and automatically recorded.

Expand Down
Loading