Fix: Remove incorrect super().startup() and super().shutdown() calls from documentation

[simons-plugins]

Bug: Documentation incorrectly instructs calling super().startup() and super().shutdown()

Summary

The Indigo skill documentation contains incorrect guidance that tells developers to call super().startup() and super().shutdown() in their plugin code. These methods do not exist in indigo.PluginBase, causing AttributeError exceptions when developers follow the documentation.

Impact

Severity: High - Breaks all plugins created using the documentation/templates

Affected Components:

• ❌ snippets/plugin-base-template.py - Template code had super().startup() and super().shutdown()
• ❌ docs/concepts/plugin-lifecycle.md - Multiple examples showing incorrect super() calls
• ❌ docs/quick-start.md - "Common Mistakes" section showed wrong pattern
• ❌ docs/troubleshooting/README.md - Debug examples had super() calls

The Problem

What the Documentation Said (WRONG)

def startup(self):
    super().startup()  # AttributeError: 'super' object has no attribute 'startup'
    self.logger.info("Starting")

def shutdown(self):
    self.logger.info("Stopping")
    super().shutdown()  # AttributeError: 'super' object has no attribute 'shutdown'

What the SDK Examples Actually Do (CORRECT)

Checked all 16 official SDK examples - ZERO call super().startup() or super().shutdown():

$ grep -r "super().startup\|super().shutdown" sdk-examples/ --include="*.py"
# No matches found

Examples:

• Example Device - Sprinkler: def startup(self): pass (no super)
• Example Device - Custom: def startup(self): self.logger.debug("startup called") (no super)
• All other examples: No super() calls in startup/shutdown

Root Cause

The documentation was written incorrectly without validating against the official SDK examples. The methods startup() and shutdown() are pure callbacks with no parent implementation in indigo.PluginBase.

Error Produced

When developers follow the documentation, they get:

Error in plugin execution startup:
File "plugin.py", line 43, in startup
type: 'super' object has no attribute 'startup'

Which Methods Actually Need super()?

Method	Needs super()?	Required?
__init__()	✅ YES	REQUIRED - super().__init__(...)
startup()	❌ NO	Do NOT call super()
shutdown()	❌ NO	Do NOT call super()
deviceStartComm()	✅ YES	Recommended - super().deviceStartComm(dev)
deviceStopComm()	✅ YES	Recommended - super().deviceStopComm(dev)
deviceUpdated()	✅ YES	Recommended - super().deviceUpdated(origDev, newDev)
variableUpdated()	✅ YES	Recommended - super().variableUpdated(origVar, newVar)

The Fix

Correct Pattern

def startup(self):
    # Note: Do NOT call super().startup() - it doesn't exist
    self.logger.info(f"{self.pluginDisplayName} starting")
    # Initialize API clients, subscribe to events, etc.

def shutdown(self):
    # Note: Do NOT call super().shutdown() - it doesn't exist
    self.logger.info(f"{self.pluginDisplayName} shutting down")
    # Clean up resources, close connections, etc.

Files Fixed

1. snippets/plugin-base-template.py

   • Removed super().startup() call
   • Removed super().shutdown() call
   • Added clarifying comments

2. docs/concepts/plugin-lifecycle.md

   • Fixed "Rules" section to say "Do NOT call super()"
   • Fixed 8+ code examples showing incorrect super() calls
   • Replaced "Forgetting to Call super()" section with "Calling super() in Wrong Methods"
   • Added notes to all startup/shutdown examples

3. docs/quick-start.md

   • Replaced "Common Mistake Welcome to indigo-claude-skill Discussions! #1" with correct guidance
   • Added table showing which methods need super()

4. docs/troubleshooting/README.md

   • Fixed debug example that showed super().startup()

5. docs/troubleshooting/common-issues.md

   • Added new troubleshooting section for AttributeError
   • Added clear table of which methods need super()
   • Added API URL construction best practices

Testing

Created a test Netro sprinkler plugin following the OLD documentation:

• ❌ Before fix: Plugin crashed with AttributeError: 'super' object has no attribute 'startup'
• ✅ After fix: Plugin starts and shuts down correctly

References

• Official SDK Examples: All 16 examples in sdk-examples/ directory
• Official Indigo Docs: https://wiki.indigodomo.com/doku.php?id=indigo_2025.1_documentation:plugin_guide
• Real-world impact: Netro plugin development session where this bug was discovered

Lesson Learned

Always validate documentation against official SDK examples before adding it to community resources. The SDK examples are the source of truth.

Summary by CodeRabbit

• Documentation

  • Clarified lifecycle guidance: do not invoke base-class startup/shutdown; updated examples and common-mistakes guidance.
  • Added device callback examples, threading best practices, input-validation patterns, dependency bundling advice, and expanded troubleshooting for API integration and startup crashes.

• Tests

  • Updated templates and example snippets to reflect the revised best practices.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Warning

Rate limit exceeded

@simons-plugins has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 11 minutes and 23 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📝 Walkthrough

Walkthrough

Updates documentation and plugin examples to remove calls to super().startup() and super().shutdown(), clarifying that those lifecycle methods are pure callbacks and that super() should only be used in __init__() and device callback methods.

Changes

Cohort / File(s)	Summary
Lifecycle docs & quick start docs/concepts/plugin-lifecycle.md, docs/quick-start.md	Removed super().startup() / super().shutdown() from examples; added notes that those base-method calls do not exist; clarified lifecycle rules and recommended super() usage (only in __init__() and device callbacks).
Troubleshooting & common issues docs/troubleshooting/README.md, docs/troubleshooting/common-issues.md	Replaced examples that called super().startup(); added an explicit entry for AttributeError from calling super().startup()/shutdown() and expanded API integration guidance (malformed URLs, rate limiting/backoff examples).
Code snippets / plugin template snippets/plugin-base-template.py	Removed super().startup() / super().shutdown() from template methods and updated docstrings to state startup/shutdown are pure callbacks and should not call super().

Sequence Diagram(s)

(omitted)

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related issues

• Bug: Documentation incorrectly instructs calling super().startup() and super().shutdown() #3 — Addresses the same erroneous super().startup() / super().shutdown() calls in examples/templates that cause AttributeError.

Poem

🐰 I nibbled through docs where super() led astray,
Startup and shutdown now keep their own way.
Only __init__ and device callbacks may call—
The rest stand alone, hopping proud and tall. 🥕

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: removing incorrect super().startup() and super().shutdown() calls from documentation, which is the primary focus across all modified files.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/concepts/plugin-lifecycle.md (1)

595-608: Checklist item contradicts the new guidance.

Line 599 states "✅ super() called in all lifecycle methods" but this directly contradicts the documentation changes in this PR. The guidance now explicitly states that startup() and shutdown() should NOT call super().

Suggested fix

 ## Resource Management Checklist
 
 - [ ] All instance variables initialized in `__init__()`
 - [ ] No Indigo database access in `__init__()`
-- [ ] `super()` called in all lifecycle methods
+- [ ] `super().__init__()` called in `__init__()` (required)
+- [ ] `super()` called in device callbacks like `deviceStartComm()` (recommended)
+- [ ] `super()` NOT called in `startup()` or `shutdown()`
 - [ ] Connections opened in `startup()`
 - [ ] Event subscriptions done in `startup()`