From d752ad7292f69b5c8fafe4a8e92acd48a90917c9 Mon Sep 17 00:00:00 2001 From: Keith Burzinski Date: Mon, 21 Jul 2025 01:22:36 -0500 Subject: [PATCH] Add copy about `static`, component image generator & large PRs --- docs/contributing/code.md | 2 ++ docs/contributing/docs.md | 8 ++++++++ docs/contributing/submitting-your-work.md | 20 ++++++++++++++++++-- 3 files changed, 28 insertions(+), 2 deletions(-) diff --git a/docs/contributing/code.md b/docs/contributing/code.md index 6b6bc1c..fe0b197 100644 --- a/docs/contributing/code.md +++ b/docs/contributing/code.md @@ -59,6 +59,8 @@ In general, we try to avoid use of external libraries. - Components **must** use the provided abstractions like `sensor`, `switch`, etc. and should inherit from either `Component` or `PollingComponent`. - Components should **not** directly access other components -- for example, to publish to MQTT topics. +- Use of `static` variables within component/platform classes is not permitted, as this is likely to cause problems + when multiple instances of the component/platform are created. - Components are required to dump their configuration using `ESP_LOGCONFIG` in the `dump_config()` method. This method is used **exclusively** to **print values** determined during `setup()` -- nothing more. - For time tracking, use `App.get_loop_component_start_time()` rather than `millis()`. Hardware time reads are slow diff --git a/docs/contributing/docs.md b/docs/contributing/docs.md index 99b8cfb..716fb5c 100644 --- a/docs/contributing/docs.md +++ b/docs/contributing/docs.md @@ -20,6 +20,14 @@ If you're not familiar with rST, see [rST syntax](#rst-syntax) for a quick prime - Dependent components (Instead, include a sentence explaining the dependency and a link to the dependency's documentation) - Pin numbers used in examples should be the string `GPIOXX` -- not a specific pin number. +- When adding (a) new component(s)/platform(s), be sure to update the [main index page](https://esphome.io/components/) + appropriately: + - Insert your new component/platform _alphabetically_ into the relevant list(s) -- do **not** just append to the + end of any given component/platform list. + - If you need an image for your new component/platform, use our + [component image generator](https://github.com/esphome/component-image-generator). You can run this in a + container locally to generate the image or summon our bot to do so by adding a comment to your PR in the + `esphome-docs` repository: `@esphomebot generate image MyNewComponent` - If a component/platform is used exclusively/primarily on a single specific board (perhaps with dedicated pin numbers), a complete configuration for the component/platform on that specific board may be included as an example _at the end of the document._ This example must be clearly identified as being for that specific hardware and it may diff --git a/docs/contributing/submitting-your-work.md b/docs/contributing/submitting-your-work.md index bcaac47..c5d6b5b 100644 --- a/docs/contributing/submitting-your-work.md +++ b/docs/contributing/submitting-your-work.md @@ -85,14 +85,30 @@ here are some tips: time commenting on/correcting your PR because you didn't name variables correctly or didn't prefix member variable accesses with `this->`, it wastes time we could be using to review other PRs which *do* follow the standards. - If you wish to take on a big project, such as refactoring a substantial section of the codebase or integrating - another open source project with ESPHome, please discuss this with us on [Discord](https://discord.gg/KhAMKrd) or + another open source project with ESPHome, please discuss this with us on [Discord](https://esphome.io/chat) or [create a discussion on GitHub](https://github.com/esphome/esphome/discussions) **before** you do all the work and attempt to submit a massive PR. - If you are not sure about how you should proceed with some changes, **please** - [discuss it with us on Discord](https://discord.gg/KhAMKrd) **before** you go do a bunch of work that we can't (for + [discuss it with us on Discord](https://esphome.io/chat) **before** you go do a bunch of work that we can't (for whatever reason) accept...and then you have to go back and re-do it all to get your PR merged. It's easier to make corrections early-on -- and we want to help you! +#### How to approach large submissions + +If you have a (very) large amount of code (thousands of lines) you want to submit: + +- [Discuss it with us on Discord](https://esphome.io/chat) **before** you begin the work. +- **Carefully plan a way to break the work into a series of smaller changes** which can be submitted independently of + each other. For example, consider a piece of sensor hardware which provides measurements of seven different + environmental parameters and can be connected via either I2C or SPI; the work might be broken into separate PRs for: + - Implementing the base "hub" component + - Extending the base for both I2C and SPI connectivity + - Adding the various sensor platforms to make available the data the sensor reports +- It's reasonable to submit all the PRs at once, but, if you do so, be sure to: + - Link them together in the PR descriptions so that reviewers can follow the work. + - Indicate the order in which the PRs should be reviewed and/or merged, if relevant. + - Minimize (the potential for) conflicts as much as reasonably possible. + ## Can I Help Review PRs? **YES! PLEASE!!!**