Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
38 changes: 38 additions & 0 deletions Sources/SystemMetrics/Docs.docc/Proposals/Proposals.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
# Proposals

Collaborate on API changes to Swift Metrics Extras by writing a proposal.

## Overview

For non-trivial changes that affect the public API, the Swift Metrics Extras project adopts a lightweight version of the [Swift Evolution](https://github.com/apple/swift-evolution/blob/main/process.md) process.

Writing a proposal first helps discuss multiple possible solutions early, apply useful feedback from other contributors, and avoid reimplementing the same feature multiple times.

While it's encouraged to get feedback by opening a pull request with a proposal early in the process, it's also important to consider the complexity of the implementation when evaluating different solutions. For example, this might mean including a link to a branch containing a prototype implementation of the feature in the pull request description.

> Note: The goal of this process is to help solicit feedback from the whole community around the project, and we will continue to refine the proposal process itself. Use your best judgement, and don't hesitate to propose changes to the proposal structure itself!

### Steps

1. Make sure there's a GitHub issue for the feature or change you would like to propose.
2. Duplicate the `SSM-NNNN.md` document and replace `NNNN` with the next available proposal number.
3. Link the GitHub issue from your proposal, and fill in the proposal.
4. Open a pull request with your proposal and solicit feedback from other contributors.
5. Once a maintainer confirms that the proposal is ready for review, the state is updated accordingly. The review period is 7 days, and ends when one of the maintainers marks the proposal as Ready for Implementation, or Deferred.
6. Before the pull request is merged, there should be an implementation ready, either in the same pull request, or a separate one, linked from the proposal.
7. The proposal is considered Approved once the implementation, proposal PRs have been merged, and, if originally disabled by a feature flag, feature flag enabled unconditionally.

If you have any questions, ask in an issue on GitHub.

### Possible review states

- Awaiting Review
- In Review
- Ready for Implementation
- In Preview
- Approved
- Deferred

## Topics

- <doc:SSM-NNNN>
49 changes: 49 additions & 0 deletions Sources/SystemMetrics/Docs.docc/Proposals/SSM-NNNN.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
# SSM-NNNN: Feature name

Feature abstract – a one sentence summary.

## Overview

- Proposal: SSM-NNNN
- Author(s): [Author 1](https://github.com/swiftdev), [Author 2](https://github.com/swiftdev)
- Status: **Awaiting Review**
- Issue: [apple/swift-metrics-extras#1](https://github.com/apple/swift-metrics-extras/issues/1)
- Implementation:
- [apple/swift-metrics-extras#1](https://github.com/apple/swift-metrics-extras/pull/1)
- Feature flag: `proposalNNNN`
- Related links:
- [Swift Evolution](https://www.swift.org/swift-evolution/)

### Introduction

A short, one-sentence overview of the feature or change.

### Motivation

Describe the problems that this proposal aims to address, and what workarounds adopters have to employ currently, if any.

### Proposed solution

Describe your solution to the problem. Provide examples and describe how they work. Show how your solution is better than current workarounds.

This section should focus on what will change for the _adopters_ of Swift Configuration.

### Detailed design

Describe the implementation of the feature, a link to a prototype implementation is encouraged here.

This section should focus on what will change for the _contributors_ to Swift Configuration.

### API stability

Discuss the API implications, making sure to considering all of:
- existing metrics data provider implementations
- existing users of `SystemMetrics`

### Future directions

Discuss any potential future improvements to the feature.

### Alternatives considered

Discuss the alternative solutions considered, even during the review process itself.