Alter stability note in README and briefly explain unstable feature #2894
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
bjoernQ
reviewed
Jan 6, 2025
README.md
Outdated
| @@ -20,7 +20,7 @@ If you have any questions, comments, or concerns, please [open an issue], [start | |||
|
|
|||
| > [!NOTE] | |||
| > | |||
| > This project is still in the relatively early stages of development, and as such there should be no expectation of API stability. A significant number of peripherals currently have drivers implemented but have varying levels of functionality. For most tasks, this should be usable already, however some more advanced or uncommon features may not yet be implemented. | |||
| > This project is still in the relatively early stages of development. A significant number of peripherals currently have drivers implemented but have varying levels of functionality. For most tasks, this should be usable already, however some more advanced or uncommon features may not yet be implemented. | |||
There was a problem hiding this comment.
I think this paragraph is a left-over from the time this repo contained only the HAL - we probably should mentioin that crates in this repo come with different stability guarantees and are at different stages of maturity
bjoernQ
reviewed
Jan 6, 2025
esp-hal/README.md
Outdated
| @@ -46,6 +46,12 @@ For help getting started with this HAL, please refer to [The Rust on ESP Book] a | |||
| [s2-trm]: https://www.espressif.com/sites/default/files/documentation/esp32-s2_technical_reference_manual_en.pdf | |||
| [s3-trm]: https://www.espressif.com/sites/default/files/documentation/esp32-s3_technical_reference_manual_en.pdf | |||
|
|
|||
| ## `unstable` feature | |||
|
|
|||
| We aim to avoid enabling experimental features automatically. Allowing automatic access could result in users unintentionally utilizing APIs that are still under development. | |||
There was a problem hiding this comment.
this is very brief and fuzzy at the same time - we should mention that the stable feature set is ... stable - and other parts guarded by the unstable feature will likely see breaking changes .... something like that
I don't think we need to explain here why we don't enable unstable by default 🤔
bugadani
approved these changes
Jan 7, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Not sure if this isn't too brief 😅
closes #2501