Skip to content

Commit

Permalink
docs: update the RFC doc (#3748)
Browse files Browse the repository at this point in the history
  • Loading branch information
@suyanhanx
suyanhanx authored Dec 13, 2023
1 parent abef22b commit f1acc91
Show file tree
Hide file tree
Showing 2 changed files with 113 additions and 13 deletions.
62 changes: 62 additions & 0 deletions core/src/docs/rfcs/README.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
# RFCs - OpenDAL Active RFC List

RFCs power OpenDAL's development.

The "RFC" (request for comments) process is intended to provide a consistent and controlled path for changes to OpenDAL (such as new features) so that all stakeholders can be confident about the direction of the project.

Many changes, including bug fixes and documentation improvements, can be implemented and reviewed via the normal GitHub pull request workflow.

Some changes, though, are "substantial" and we ask that these be put through a bit of a design process and produce a consensus among the OpenDAL community.

### Which kinds of changes require an RFC?

Any substantial change or addition to the project that would require a significant amount of work to implement should generally be an RFC.

Some examples include:

- A new feature that creates a new public API or raw API.
- The removal of features that already shipped as part of the release.
- A big refactor of existing code or reorganization of code into new modules.

Those are just a few examples. Ultimately, the judgment call of what constitutes a big enough change to warrant an RFC is left to the project maintainers.

If you submit a pull request to implement a new feature without going through the RFC process, it may be closed with a polite request to submit an RFC first.

## Before creating the RFC

Preparing in advance before submitting an RFC hastily can increase its chances of being accepted. If you have proposals to make, it is advisable to engage in some preliminary groundwork to facilitate a smoother process.

It is great to seek feedback from other project developers first, as this can help validate the viability of the RFC. To ensure a sustained impact on the project, it is important to work together and reach a consensus.

Common preparatory steps include presenting your idea on platforms such as GitHub [issues](https://github.com/apache/incubator-opendal/issues/) or [discussions](https://github.com/apache/incubator-opendal/discussions/categories/ideas), or engaging in discussions through our [email list](https://opendal.apache.org/community/#mailing-list) or [Discord server](https://discord.gg/XQy8yGR2dg).

## The RFC process

- Fork the [OpenDAL repo](https://github.com/apache/incubator-opendal) and create your branch from `main`.
- Copy [`0000_example.md`] to `0000-my-feature.md` (where "my-feature" is descriptive). Don't assign an RFC number yet; This is going to be the PR number, and we'll rename the file accordingly if the RFC is accepted.
- Submit a pull request. As a pull request, the RFC will receive design feedback from the larger community, and the author should be prepared to revise it in response.
- Now that your RFC has an open pull request, use the issue number of this PR to update your `0000-` prefix to that number.
- Build consensus and integrate feedback. RFCs that have broad support are much more likely to make progress than those that don't receive any comments. Feel free to reach OpenDAL maintainers for help.
- RFCs rarely go through this process unchanged, especially as alternatives and drawbacks are shown. You can make edits, big and small, to the RFC to clarify or change the design, but make changes as new commits to the pull request, and leave a comment on the pull request explaining your changes. Specifically, do not squash or rebase commits after they are visible on the pull request.
- The RFC pull request lasts for three days after the last update. After that, the RFC will be accepted or declined based on the consensus reached in the discussion.
- For the accepting of an RFC, we will require approval from at least three maintainers.
- Once the RFC is accepted, please create a tracking issue and update links in RFC. And then the PR will be merged and the RFC will become 'active' status.

## Implementing an RFC

An active RFC does not indicate the priority assigned to its implementation,
nor does it imply that a developer has been specifically assigned the task of implementing the feature.

The RFC author is encouraged to submit an implementation after the RFC has been accepted.
Nevertheless, it is not obligatory for them to do so.

Accepted RFCs may represent features that can wait until a developer chooses to work on them.
Each accepted RFC is associated with an issue in the OpenDAL repository, which tracks its implementation.

If you are interested in implementing an RFC but are unsure if someone else is already working on it,
feel free to inquire by leaving a comment on the associated issue.

## Some useful tips

- The author of an RFC may not be the same one as the implementor. Therefore, when submitting an RFC, it is advisable to include sufficient information.
- If modifications are needed for an accepted RFC, please submit a new pull request or create a new RFC to propose changes.
64 changes: 51 additions & 13 deletions core/src/docs/rfcs/mod.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,166 +15,204 @@
// specific language governing permissions and limitations
// under the License.

//! RFCs power OpenDAL's development.
//!
//! To add new features and big refactors:
//!
//! - Start a new RFCs with the template [`rfc_0000_example`].
//! - Submit PR and assign the RFC number with the PR number.
//! - Request reviews from OpenDAL maintainers.
//! - Create a tracking issue and update links in RFC after approval.
//!
//! Some useful tips:
//!
//! - Start a pre-propose in [discussion](https://github.com/apache/incubator-opendal/discussions/categories/ideas) to communicate quickly.
//! - The proposer of RFC may not be the same person as the implementor. Try to include enough information in RFC itself.
#![doc = include_str!("README.md")]

/// RFC example
#[doc = include_str!("0000_example.md")]
pub mod rfc_0000_example {}

/// Object native API
#[doc = include_str!("0041_object_native_api.md")]
pub mod rfc_0041_object_native_api {}

/// Error handle
#[doc = include_str!("0044_error_handle.md")]
pub mod rfc_0044_error_handle {}

/// Auto region
#[doc = include_str!("0057_auto_region.md")]
pub mod rfc_0057_auto_region {}

/// Object stream
#[doc = include_str!("0069_object_stream.md")]
pub mod rfc_0069_object_stream {}

/// Limited reader
#[doc = include_str!("0090_limited_reader.md")]
pub mod rfc_0090_limited_reader {}

/// Path normalization
#[doc = include_str!("0112_path_normalization.md")]
pub mod rfc_0112_path_normalization {}

/// Async streaming IO
#[doc = include_str!("0191_async_streaming_io.md")]
pub mod rfc_0191_async_streaming_io {}

/// Remove credential
#[doc = include_str!("0203_remove_credential.md")]
pub mod rfc_0203_remove_credential {}

/// Create dir
#[doc = include_str!("0221_create_dir.md")]
pub mod rfc_0221_create_dir {}

/// Retryable error
#[doc = include_str!("0247_retryable_error.md")]
pub mod rfc_0247_retryable_error {}

/// Object ID
#[doc = include_str!("0293_object_id.md")]
pub mod rfc_0293_object_id {}

/// Dir entry
#[doc = include_str!("0337_dir_entry.md")]
pub mod rfc_0337_dir_entry {}

/// Accessor capabilities
#[doc = include_str!("0409_accessor_capabilities.md")]
pub mod rfc_0409_accessor_capabilities {}

/// Presign
#[doc = include_str!("0413_presign.md")]
pub mod rfc_0413_presign {}

/// Command line interface
#[doc = include_str!("0423_command_line_interface.md")]
pub mod rfc_0423_command_line_interface {}

/// Init from iter
#[doc = include_str!("0429_init_from_iter.md")]
pub mod rfc_0429_init_from_iter {}

/// Multipart
#[doc = include_str!("0438_multipart.md")]
pub mod rfc_0438_multipart {}

/// Gateway
#[doc = include_str!("0443_gateway.md")]
pub mod rfc_0443_gateway {}

/// New builder
#[doc = include_str!("0501_new_builder.md")]
pub mod rfc_0501_new_builder {}

/// Write refactor
#[doc = include_str!("0554_write_refactor.md")]
pub mod rfc_0554_write_refactor {}

/// List metadata reuse
#[doc = include_str!("0561_list_metadata_reuse.md")]
pub mod rfc_0561_list_metadata_reuse {}

/// Blocking API
#[doc = include_str!("0599_blocking_api.md")]
pub mod rfc_0599_blocking_api {}

/// Redis service
#[doc = include_str!("0623_redis_service.md")]
pub mod rfc_0623_redis_service {}

/// Split capabilities
#[doc = include_str!("0627_split_capabilities.md")]
pub mod rfc_0627_split_capabilities {}

/// Path in accessor
#[doc = include_str!("0661_path_in_accessor.md")]
pub mod rfc_0661_path_in_accessor {}

/// Generic KV services
#[doc = include_str!("0793_generic_kv_services.md")]
pub mod rfc_0793_generic_kv_services {}

/// Object reader
#[doc = include_str!("0926_object_reader.md")]
pub mod rfc_0926_object_reader {}

/// Refactor error
#[doc = include_str!("0977_refactor_error.md")]
pub mod rfc_0977_refactor_error {}

/// Object handler
#[doc = include_str!("1085_object_handler.md")]
pub mod rfc_1085_object_handler {}

/// Object metadataer
#[doc = include_str!("1391_object_metadataer.md")]
pub mod rfc_1391_object_metadataer {}

/// Query based metadata
#[doc = include_str!("1398_query_based_metadata.md")]
pub mod rfc_1398_query_based_metadata {}

/// Object writer
#[doc = include_str!("1420_object_writer.md")]
pub mod rfc_1420_object_writer {}

/// Remove object concept
#[doc = include_str!("1477_remove_object_concept.md")]
pub mod rfc_1477_remove_object_concept {}

/// Operation extension
#[doc = include_str!("1735_operation_extension.md")]
pub mod rfc_1735_operation_extension {}

/// Writer sink API
#[doc = include_str!("2083_writer_sink_api.md")]
pub mod rfc_2083_writer_sink_api {}

/// Append API
#[doc = include_str!("2133_append_api.md")]
pub mod rfc_2133_append_api {}

/// Chain based operator API
#[doc = include_str!("2299_chain_based_operator_api.md")]
pub mod rfc_2299_chain_based_operator_api {}

/// Object versioning
#[doc = include_str!("2602_object_versioning.md")]
pub mod rfc_2602_object_versioning {}

/// Merge append into write
#[doc = include_str!("2758_merge_append_into_write.md")]
pub mod rfc_2758_merge_append_into_write {}

/// Lister API
#[doc = include_str!("2774_lister_api.md")]
pub mod rfc_2774_lister_api {}

/// List with metakey
#[doc = include_str!("2779_list_with_metakey.md")]
pub mod rfc_2779_list_with_metakey {}

/// Native capability
#[doc = include_str!("2852_native_capability.md")]
pub mod rfc_2852_native_capability {}

/// Remove write copy from
#[doc = include_str!("3017_remove_write_copy_from.md")]
pub mod rfc_3017_remove_write_copy_from {}

/// Config
#[doc = include_str!("3197_config.md")]
pub mod rfc_3197_config {}

/// Align list API
#[doc = include_str!("3232_align_list_api.md")]
pub mod rfc_3232_align_list_api {}

/// List prefix
#[doc = include_str!("3243_list_prefix.md")]
pub mod rfc_3243_list_prefix {}

/// Lazy reader
#[doc = include_str!("3356_lazy_reader.md")]
pub mod rfc_3356_lazy_reader {}

/// List recursive
#[doc = include_str!("3526_list_recursive.md")]
pub mod rfc_3526_list_recursive {}

/// Concurrent stat in list
#[doc = include_str!("3574_concurrent_stat_in_list.md")]
pub mod rfc_3574_concurrent_stat_in_list {}

0 comments on commit f1acc91

Please sign in to comment.