Update module reconfiguration lifecycle docs by shannonbradshaw · Pull Request #5042 · viamrobotics/docs

shannonbradshaw · 2026-05-06T09:16:21Z

Source changes

[APP-16062] Reapply Remove Reconfigure + Rebuild stale module-internal dependents when a dependency is re-added rdk#5944: Remove Reconfigure from the Resource interface; modular resources are now always rebuilt (close + re-create) instead of reconfigured in place.

Docs changes

docs/build-modules/module-reference.md: Removed the "In-place reconfigure" row from the Python/Go defaults table (Python's reconfigure() via the Reconfigurable protocol is no longer called by viam-server). Added a paragraph clarifying that viam-server always rebuilds modular resources. Updated the ReconfigureResource RPC description to reflect it now rebuilds rather than updates in place.
static/include/components/apis/overrides/protos/sensor.Reconfigure.md: Updated the override description to state that modular resources are rebuilt rather than reconfigured atomically in place.

How I found these

Xref lookup: search-patterns.yaml entry for Resource.Reconfigure (discovered 2026-04-15)
Grep matches: grep -rl "Reconfigure" docs/build-modules/ found 4 pages; the module-reference.md table had the incorrect Python claim

Generated by daily docs change agent

Generated by Claude Code

viam-server now always rebuilds modular resources (close + re-create) when their configuration changes. In-place reconfiguration via Reconfigure() is no longer supported for modular resources in any language. This removes the incorrect claim that Python modules can implement reconfigure() to handle config changes in place. Source: viamrobotics/rdk#5944 https://claude.ai/code/session_01Xd7GAtzjRzypiJK1amk4Uu

netlify · 2026-05-06T09:16:28Z

✅ Deploy Preview for viam-docs ready!

Name	Link
🔨 Latest commit	`45c5ae7`
🔍 Latest deploy log	https://app.netlify.com/projects/viam-docs/deploys/6a1600fa0e3618000821c9d6
😎 Deploy Preview	https://deploy-preview-5042--viam-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 38 (🔴 down 6 from production) Accessibility: 99 (no change from production) Best Practices: 92 (🔴 down 8 from production) SEO: 92 (no change from production) PWA: 60 (no change from production) View the detailed breakdown and full score reports

To edit notification comments on pull requests, go to your Netlify project configuration.

shannonbradshaw · 2026-05-08T09:15:05Z

Hold: source change reverted. The RDK change this PR documents (viamrobotics/rdk#5944, Remove-Reconfigure) was reverted by viamrobotics/rdk#5997 on 2026-05-07. Reconfigure is back on the Resource interface temporarily while the cascade-fix bakes on main.

The #5997 PR description says: "To reland Remove-Reconfigure: revert this PR." So Remove-Reconfigure is expected to re-land in 1-2 weeks.

Recommendation: Do not merge this PR until Remove-Reconfigure re-lands. Once it does, this PR's changes will be correct again and can be merged (possibly with minor updates if the re-land differs from #5944).

Generated by daily docs change agent

Generated by Claude Code

viamrobotics-overwatch · 2026-05-11T15:12:59Z

Hey @shannonbradshaw — CI is green and no reviewer is assigned yet. Could you request one when you have a chance?

Auto-comment from overwatch. Will not re-nudge for 7 days.

viamrobotics-overwatch · 2026-05-18T15:14:34Z

Hey @shannonbradshaw — CI is green and no reviewer is assigned yet. Could you request one when you have a chance?

Auto-comment from overwatch. Will not re-nudge for 7 days.

viamrobotics-overwatch · 2026-05-26T15:15:37Z

Hey @shannonbradshaw — CI is green and no reviewer is assigned yet. Could you request one when you have a chance?

Auto-comment from overwatch. Will not re-nudge for 7 days.

danielbotros

LGTM, but I would hold off on merging since we reverted the linked PR to let the additional fixes bake and will land the actual remove reconfigure in the next week or so.

danielbotros · 2026-05-26T20:08:18Z

@@ -240,12 +240,16 @@ if __name__ == '__main__':

 The default behavior when you don't implement a method:

-| Behavior                 | Go                                                           | Python                                                                                   |
-| ------------------------ | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
-| Rebuild on config change | Default (`viam-server` destroys and re-creates the resource) | Default (`viam-server` destroys and re-creates the resource)                             |
-| In-place reconfigure     | Not supported for modular resources                          | Implement `reconfigure()` (called if your class satisfies the `Reconfigurable` protocol) |
-| No-op close              | Embed `resource.TriviallyCloseable`                          | Default on `ResourceBase`                                                                |
-| Skip config validation   | Embed `resource.TriviallyValidateConfig`                     | Default on `EasyResource`                                                                |
+| Behavior                 | Go                                                           | Python                                                       |
+| ------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
+| Rebuild on config change | Default (`viam-server` destroys and re-creates the resource) | Default (`viam-server` destroys and re-creates the resource) |
+| No-op close              | Embed `resource.TriviallyCloseable`                          | Default on `ResourceBase`                                    |
+| Skip config validation   | Embed `resource.TriviallyValidateConfig`                     | Default on `EasyResource`                                    |
+
+`viam-server` always rebuilds modular resources when their configuration
+changes. It removes the existing resource instance and creates a new one
+using the constructor. In-place reconfiguration is not supported for
+modular resources in any language.


The rebuild row doesn't really fit the structure of this table anymore since there is no default / not-default behavior, the behavior is to always rebuild. It can probably be dropped and the paragraph at the bottom explaining how modular resources are always rebuilt can do the explaining. Also, rebuilds happen when dependencies change as well, if worth mentioning.

nit: As an aside. this table structure was a little confusing to me. I interpreted as: default behavior if you don't implement a Close method is a no-op close, which embeds resource.TriviallyCloseable. But it should be conveyed the other way around. If you embed resource.TriviallyCloseable then you get the default behavior of a no-op close.

danielbotros · 2026-05-26T20:13:42Z

+| --------------------- | ----------------------------------------------------------------------------------- |
+| `Ready`               | Handshake: module returns its supported API/model pairs.                            |
+| `AddResource`         | Create a new resource instance from config.                                         |
+| `ReconfigureResource` | Rebuild an existing resource with new config (removes and re-creates the resource). |


I think this is clear as-is, and the distinction is mostly one of internal mechanics but since we mention:

In-place reconfiguration is not supported for modular resources in any language.

consider mentioning the name ReconfigureResource is retained for compatibility reasons for more clarity.

danielbotros · 2026-05-26T20:17:57Z

 Reconfigure this resource.
-Reconfigure must reconfigure the resource atomically and in place.
+For modular resources, reconfiguration destroys the existing resource instance and creates a new one using the constructor.


Maybe we can move away from the language of reconfigure towards reconstruction? i.e.

Reconstruct this resource. For modular resources, reconstruction destroys...

…nstruct language - Drop "Rebuild on config change" row from defaults table since rebuilds are universal, not a default-vs-custom behavior. Note dependency changes also trigger rebuilds. - Add compatibility note to ReconfigureResource RPC description. - Use "Reconstruct" language in sensor.Reconfigure override. https://claude.ai/code/session_01Xd7GAtzjRzypiJK1amk4Uu

shannonbradshaw · 2026-05-28T13:00:10Z

Thanks, @danielbotros. Will hold off on merging.

viambot added the safe to build This pull request is marked safe to build from a trusted zone label May 6, 2026

shannonbradshaw requested a review from danielbotros May 26, 2026 18:43

danielbotros approved these changes May 26, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update module reconfiguration lifecycle docs#5042

Update module reconfiguration lifecycle docs#5042
shannonbradshaw wants to merge 2 commits into
mainfrom
claude/update-module-reconfigure-lifecycle

shannonbradshaw commented May 6, 2026

Uh oh!

netlify Bot commented May 6, 2026 •

edited

Loading

Uh oh!

shannonbradshaw commented May 8, 2026

Uh oh!

viamrobotics-overwatch Bot commented May 11, 2026

Uh oh!

viamrobotics-overwatch Bot commented May 18, 2026

Uh oh!

viamrobotics-overwatch Bot commented May 26, 2026

Uh oh!

danielbotros left a comment

Uh oh!

danielbotros May 26, 2026

Uh oh!

danielbotros May 26, 2026

Uh oh!

danielbotros May 26, 2026

Uh oh!

shannonbradshaw commented May 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

shannonbradshaw commented May 6, 2026

Source changes

Docs changes

How I found these

Uh oh!

netlify Bot commented May 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for viam-docs ready!

Uh oh!

shannonbradshaw commented May 8, 2026

Uh oh!

viamrobotics-overwatch Bot commented May 11, 2026

Uh oh!

viamrobotics-overwatch Bot commented May 18, 2026

Uh oh!

viamrobotics-overwatch Bot commented May 26, 2026

Uh oh!

danielbotros left a comment

Choose a reason for hiding this comment

Uh oh!

danielbotros May 26, 2026

Choose a reason for hiding this comment

Uh oh!

danielbotros May 26, 2026

Choose a reason for hiding this comment

Uh oh!

danielbotros May 26, 2026

Choose a reason for hiding this comment

Uh oh!

shannonbradshaw commented May 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

netlify Bot commented May 6, 2026 •

edited

Loading