jpawlowski/hass.tibber_prices
1
0
Fork 0
mirror of https://github.com/jpawlowski/hass.tibber_prices.git synced 2026-03-30 05:13:40 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2
hass.tibber_prices/developer/refactoring-guide.html
github-actions[bot] e9aea64a2e deploy: 6898c126e3
2025-12-06 01:42:39 +00:00

264 lines
No EOL
66 KiB
HTML
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!doctype html>
<html lang="en" dir="ltr" class="docs-wrapper plugin-docs plugin-id-default docs-version-current docs-doc-page docs-doc-id-refactoring-guide" data-has-hydrated="false">
<head>
<meta charset="UTF-8">
<meta name="generator" content="Docusaurus v3.9.2">
<title data-rh="true">Refactoring Guide | Tibber Prices - Developer Guide</title><meta data-rh="true" name="viewport" content="width=device-width,initial-scale=1"><meta data-rh="true" name="twitter:card" content="summary_large_image"><meta data-rh="true" property="og:image" content="https://jpawlowski.github.io/hass.tibber_prices/developer/img/social-card.png"><meta data-rh="true" name="twitter:image" content="https://jpawlowski.github.io/hass.tibber_prices/developer/img/social-card.png"><meta data-rh="true" property="og:url" content="https://jpawlowski.github.io/hass.tibber_prices/developer/refactoring-guide"><meta data-rh="true" property="og:locale" content="en"><meta data-rh="true" name="docusaurus_locale" content="en"><meta data-rh="true" name="docsearch:language" content="en"><meta data-rh="true" name="docusaurus_version" content="current"><meta data-rh="true" name="docusaurus_tag" content="docs-default-current"><meta data-rh="true" name="docsearch:version" content="current"><meta data-rh="true" name="docsearch:docusaurus_tag" content="docs-default-current"><meta data-rh="true" property="og:title" content="Refactoring Guide | Tibber Prices - Developer Guide"><meta data-rh="true" name="description" content="This guide explains how to plan and execute major refactorings in this project."><meta data-rh="true" property="og:description" content="This guide explains how to plan and execute major refactorings in this project."><link data-rh="true" rel="icon" href="/hass.tibber_prices/developer/img/logo.svg"><link data-rh="true" rel="canonical" href="https://jpawlowski.github.io/hass.tibber_prices/developer/refactoring-guide"><link data-rh="true" rel="alternate" href="https://jpawlowski.github.io/hass.tibber_prices/developer/refactoring-guide" hreflang="en"><link data-rh="true" rel="alternate" href="https://jpawlowski.github.io/hass.tibber_prices/developer/refactoring-guide" hreflang="x-default"><script data-rh="true" type="application/ld+json">{"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Refactoring Guide","item":"https://jpawlowski.github.io/hass.tibber_prices/developer/refactoring-guide"}]}</script><link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin="anonymous">
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&amp;family=Space+Grotesk:wght@500;600;700&amp;display=swap"><link rel="stylesheet" href="/hass.tibber_prices/developer/assets/css/styles.be4f3d68.css">
<script src="/hass.tibber_prices/developer/assets/js/runtime~main.09b7b31a.js" defer="defer"></script>
<script src="/hass.tibber_prices/developer/assets/js/main.5eb4cf38.js" defer="defer"></script>
</head>
<body class="navigation-with-keyboard">
<svg style="display: none;"><defs>
<symbol id="theme-svg-external-link" viewBox="0 0 24 24"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"/></symbol>
</defs></svg>
<script>!function(){var t=function(){try{return new URLSearchParams(window.location.search).get("docusaurus-theme")}catch(t){}}()||function(){try{return window.localStorage.getItem("theme")}catch(t){}}();document.documentElement.setAttribute("data-theme",t||(window.matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light")),document.documentElement.setAttribute("data-theme-choice",t||"system")}(),function(){try{const c=new URLSearchParams(window.location.search).entries();for(var[t,e]of c)if(t.startsWith("docusaurus-data-")){var a=t.replace("docusaurus-data-","data-");document.documentElement.setAttribute(a,e)}}catch(t){}}()</script><div id="__docusaurus"><link rel="preload" as="image" href="/hass.tibber_prices/developer/img/logo.svg"><div role="region" aria-label="Skip to main content"><a class="skipToContent_fXgn" href="#__docusaurus_skipToContent_fallback">Skip to main content</a></div><nav aria-label="Main" class="theme-layout-navbar navbar navbar--fixed-top"><div class="navbar__inner"><div class="theme-layout-navbar-left navbar__items"><button aria-label="Toggle navigation bar" aria-expanded="false" class="navbar__toggle clean-btn" type="button"><svg width="30" height="30" viewBox="0 0 30 30" aria-hidden="true"><path stroke="currentColor" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2" d="M4 7h22M4 15h22M4 23h22"></path></svg></button><a class="navbar__brand" href="/hass.tibber_prices/developer/"><div class="navbar__logo"><img src="/hass.tibber_prices/developer/img/logo.svg" alt="Tibber Prices Integration Logo" class="themedComponent_mlkZ themedComponent--light_NVdE"><img src="/hass.tibber_prices/developer/img/logo.svg" alt="Tibber Prices Integration Logo" class="themedComponent_mlkZ themedComponent--dark_xIcU"></div><b class="navbar__title text--truncate">Tibber Prices HA</b></a><a class="navbar__item navbar__link" href="/hass.tibber_prices/developer/intro">Developer Guide</a><a href="https://jpawlowski.github.io/hass.tibber_prices/user/" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link">User Docs<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a></div><div class="theme-layout-navbar-right navbar__items navbar__items--right"><a class="navbar__item navbar__link" href="/hass.tibber_prices/developer/refactoring-guide">Next 🚧</a><a href="https://github.com/jpawlowski/hass.tibber_prices" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link">GitHub<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a><div class="toggle_vylO colorModeToggle_DEke"><button class="clean-btn toggleButton_gllP toggleButtonDisabled_aARS" type="button" disabled="" title="system mode" aria-label="Switch between dark and light mode (currently system mode)"><svg viewBox="0 0 24 24" width="24" height="24" aria-hidden="true" class="toggleIcon_g3eP lightToggleIcon_pyhR"><path fill="currentColor" d="M12,9c1.65,0,3,1.35,3,3s-1.35,3-3,3s-3-1.35-3-3S10.35,9,12,9 M12,7c-2.76,0-5,2.24-5,5s2.24,5,5,5s5-2.24,5-5 S14.76,7,12,7L12,7z M2,13l2,0c0.55,0,1-0.45,1-1s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S1.45,13,2,13z M20,13l2,0c0.55,0,1-0.45,1-1 s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S19.45,13,20,13z M11,2v2c0,0.55,0.45,1,1,1s1-0.45,1-1V2c0-0.55-0.45-1-1-1S11,1.45,11,2z M11,20v2c0,0.55,0.45,1,1,1s1-0.45,1-1v-2c0-0.55-0.45-1-1-1C11.45,19,11,19.45,11,20z M5.99,4.58c-0.39-0.39-1.03-0.39-1.41,0 c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0s0.39-1.03,0-1.41L5.99,4.58z M18.36,16.95 c-0.39-0.39-1.03-0.39-1.41,0c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0c0.39-0.39,0.39-1.03,0-1.41 L18.36,16.95z M19.42,5.99c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06c-0.39,0.39-0.39,1.03,0,1.41 s1.03,0.39,1.41,0L19.42,5.99z M7.05,18.36c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06 c-0.39,0.39-0.39,1.03,0,1.41s1.03,0.39,1.41,0L7.05,18.36z"></path></svg><svg viewBox="0 0 24 24" width="24" height="24" aria-hidden="true" class="toggleIcon_g3eP darkToggleIcon_wfgR"><path fill="currentColor" d="M9.37,5.51C9.19,6.15,9.1,6.82,9.1,7.5c0,4.08,3.32,7.4,7.4,7.4c0.68,0,1.35-0.09,1.99-0.27C17.45,17.19,14.93,19,12,19 c-3.86,0-7-3.14-7-7C5,9.07,6.81,6.55,9.37,5.51z M12,3c-4.97,0-9,4.03-9,9s4.03,9,9,9s9-4.03,9-9c0-0.46-0.04-0.92-0.1-1.36 c-0.98,1.37-2.58,2.26-4.4,2.26c-2.98,0-5.4-2.42-5.4-5.4c0-1.81,0.89-3.42,2.26-4.4C12.92,3.04,12.46,3,12,3L12,3z"></path></svg><svg viewBox="0 0 24 24" width="24" height="24" aria-hidden="true" class="toggleIcon_g3eP systemToggleIcon_QzmC"><path fill="currentColor" d="m12 21c4.971 0 9-4.029 9-9s-4.029-9-9-9-9 4.029-9 9 4.029 9 9 9zm4.95-13.95c1.313 1.313 2.05 3.093 2.05 4.95s-0.738 3.637-2.05 4.95c-1.313 1.313-3.093 2.05-4.95 2.05v-14c1.857 0 3.637 0.737 4.95 2.05z"></path></svg></button></div><div class="navbarSearchContainer_Bca1"><div class="navbar__search"><span aria-label="expand searchbar" role="button" class="search-icon" tabindex="0"></span><input id="search_input_react" type="search" placeholder="Loading..." aria-label="Search" class="navbar__search-input search-bar" disabled=""></div></div></div></div><div role="presentation" class="navbar-sidebar__backdrop"></div></nav><div id="__docusaurus_skipToContent_fallback" class="theme-layout-main main-wrapper mainWrapper_z2l0"><div class="docsWrapper_hBAB"><button aria-label="Scroll back to top" class="clean-btn theme-back-to-top-button backToTopButton_sjWU" type="button"></button><div class="docRoot_UBD9"><aside class="theme-doc-sidebar-container docSidebarContainer_YfHR"><div class="sidebarViewport_aRkj"><div class="sidebar_njMd"><nav aria-label="Docs sidebar" class="menu thin-scrollbar menu_SIkG"><ul class="theme-doc-sidebar-menu menu__list"><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1 menu__list-item"><a class="menu__link" href="/hass.tibber_prices/developer/intro"><span title="Developer Documentation" class="linkLabel_WmDU">Developer Documentation</span></a></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item"><div class="menu__list-item-collapsible"><a class="categoryLink_byQd menu__link menu__link--sublist menu__link--sublist-caret" role="button" aria-expanded="true" href="/hass.tibber_prices/developer/architecture"><span title="🏗️ Architecture" class="categoryLinkLabel_W154">🏗️ Architecture</span></a></div><ul class="menu__list"><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/hass.tibber_prices/developer/architecture"><span title="Architecture" class="linkLabel_WmDU">Architecture</span></a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/hass.tibber_prices/developer/timer-architecture"><span title="Timer Architecture" class="linkLabel_WmDU">Timer Architecture</span></a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/hass.tibber_prices/developer/caching-strategy"><span title="Caching Strategy" class="linkLabel_WmDU">Caching Strategy</span></a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/hass.tibber_prices/developer/api-reference"><span title="API Reference" class="linkLabel_WmDU">API Reference</span></a></li></ul></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item"><div class="menu__list-item-collapsible"><a class="categoryLink_byQd menu__link menu__link--sublist menu__link--sublist-caret" role="button" aria-expanded="true" href="/hass.tibber_prices/developer/setup"><span title="💻 Development" class="categoryLinkLabel_W154">💻 Development</span></a></div><ul class="menu__list"><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/hass.tibber_prices/developer/setup"><span title="Development Setup" class="linkLabel_WmDU">Development Setup</span></a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/hass.tibber_prices/developer/coding-guidelines"><span title="Coding Guidelines" class="linkLabel_WmDU">Coding Guidelines</span></a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/hass.tibber_prices/developer/critical-patterns"><span title="Critical Behavior Patterns - Testing Guide" class="linkLabel_WmDU">Critical Behavior Patterns - Testing Guide</span></a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/hass.tibber_prices/developer/debugging"><span title="Debugging Guide" class="linkLabel_WmDU">Debugging Guide</span></a></li></ul></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item"><div class="menu__list-item-collapsible"><a class="categoryLink_byQd menu__link menu__link--sublist menu__link--sublist-caret menu__link--active" role="button" aria-expanded="true" href="/hass.tibber_prices/developer/period-calculation-theory"><span title="📐 Advanced Topics" class="categoryLinkLabel_W154">📐 Advanced Topics</span></a></div><ul class="menu__list"><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/hass.tibber_prices/developer/period-calculation-theory"><span title="Period Calculation Theory" class="linkLabel_WmDU">Period Calculation Theory</span></a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link menu__link--active" aria-current="page" tabindex="0" href="/hass.tibber_prices/developer/refactoring-guide"><span title="Refactoring Guide" class="linkLabel_WmDU">Refactoring Guide</span></a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/hass.tibber_prices/developer/performance"><span title="Performance Optimization" class="linkLabel_WmDU">Performance Optimization</span></a></li></ul></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item"><div class="menu__list-item-collapsible"><a class="categoryLink_byQd menu__link menu__link--sublist menu__link--sublist-caret" role="button" aria-expanded="true" href="/hass.tibber_prices/developer/contributing"><span title="📝 Contributing" class="categoryLinkLabel_W154">📝 Contributing</span></a></div><ul class="menu__list"><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/hass.tibber_prices/developer/contributing"><span title="Contributing Guide" class="linkLabel_WmDU">Contributing Guide</span></a></li></ul></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item"><div class="menu__list-item-collapsible"><a class="categoryLink_byQd menu__link menu__link--sublist menu__link--sublist-caret" role="button" aria-expanded="true" href="/hass.tibber_prices/developer/release-management"><span title="🚀 Release" class="categoryLinkLabel_W154">🚀 Release</span></a></div><ul class="menu__list"><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/hass.tibber_prices/developer/release-management"><span title="Release Notes Generation" class="linkLabel_WmDU">Release Notes Generation</span></a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/hass.tibber_prices/developer/testing"><span title="Testing" class="linkLabel_WmDU">Testing</span></a></li></ul></li></ul></nav><button type="button" title="Collapse sidebar" aria-label="Collapse sidebar" class="button button--secondary button--outline collapseSidebarButton_PEFL"><svg width="20" height="20" aria-hidden="true" class="collapseSidebarButtonIcon_kv0_"><g fill="#7a7a7a"><path d="M9.992 10.023c0 .2-.062.399-.172.547l-4.996 7.492a.982.982 0 01-.828.454H1c-.55 0-1-.453-1-1 0-.2.059-.403.168-.551l4.629-6.942L.168 3.078A.939.939 0 010 2.528c0-.548.45-.997 1-.997h2.996c.352 0 .649.18.828.45L9.82 9.472c.11.148.172.347.172.55zm0 0"></path><path d="M19.98 10.023c0 .2-.058.399-.168.547l-4.996 7.492a.987.987 0 01-.828.454h-3c-.547 0-.996-.453-.996-1 0-.2.059-.403.168-.551l4.625-6.942-4.625-6.945a.939.939 0 01-.168-.55 1 1 0 01.996-.997h3c.348 0 .649.18.828.45l4.996 7.492c.11.148.168.347.168.55zm0 0"></path></g></svg></button></div></div></aside><main class="docMainContainer_TBSr"><div class="container padding-top--md padding-bottom--lg"><div class="row"><div class="col docItemCol_VOVn"><div class="theme-doc-version-banner alert alert--warning margin-bottom--md" role="alert"><div>This is unreleased documentation for <!-- -->Tibber Prices - Developer Guide<!-- --> <b>Next 🚧</b> version.</div><div class="margin-top--md">For up-to-date documentation, see the <b><a href="/hass.tibber_prices/developer/refactoring-guide">latest version</a></b> (<!-- -->Next 🚧<!-- -->).</div></div><div class="docItemContainer_Djhp"><article><nav class="theme-doc-breadcrumbs breadcrumbsContainer_Z_bl" aria-label="Breadcrumbs"><ul class="breadcrumbs"><li class="breadcrumbs__item"><a aria-label="Home page" class="breadcrumbs__link" href="/hass.tibber_prices/developer/"><svg viewBox="0 0 24 24" class="breadcrumbHomeIcon_YNFT"><path d="M10 19v-5h4v5c0 .55.45 1 1 1h3c.55 0 1-.45 1-1v-7h1.7c.46 0 .68-.57.33-.87L12.67 3.6c-.38-.34-.96-.34-1.34 0l-8.36 7.53c-.34.3-.13.87.33.87H5v7c0 .55.45 1 1 1h3c.55 0 1-.45 1-1z" fill="currentColor"></path></svg></a></li><li class="breadcrumbs__item"><span class="breadcrumbs__link">📐 Advanced Topics</span></li><li class="breadcrumbs__item breadcrumbs__item--active"><span class="breadcrumbs__link">Refactoring Guide</span></li></ul></nav><span class="theme-doc-version-badge badge badge--secondary">Version: Next 🚧</span><div class="tocCollapsible_ETCw theme-doc-toc-mobile tocMobile_ITEo"><button type="button" class="clean-btn tocCollapsibleButton_TO0P">On this page</button></div><div class="theme-doc-markdown markdown"><header><h1>Refactoring Guide</h1></header>
<p>This guide explains how to plan and execute major refactorings in this project.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="when-to-plan-a-refactoring">When to Plan a Refactoring<a href="#when-to-plan-a-refactoring" class="hash-link" aria-label="Direct link to When to Plan a Refactoring" title="Direct link to When to Plan a Refactoring" translate="no">​</a></h2>
<p>Not every code change needs a detailed plan. Create a refactoring plan when:</p>
<p>🔴 <strong>Major changes requiring planning:</strong></p>
<ul>
<li class="">Splitting modules into packages (&gt;5 files affected, &gt;500 lines moved)</li>
<li class="">Architectural changes (new packages, module restructuring)</li>
<li class="">Breaking changes (API changes, config format migrations)</li>
</ul>
<p>🟡 <strong>Medium changes that might benefit from planning:</strong></p>
<ul>
<li class="">Complex features with multiple moving parts</li>
<li class="">Changes affecting many files (&gt;3 files, unclear best approach)</li>
<li class="">Refactorings with unclear scope</li>
</ul>
<p>🟢 <strong>Small changes - no planning needed:</strong></p>
<ul>
<li class="">Bug fixes (straightforward, <code>&lt;</code>100 lines)</li>
<li class="">Small features (<code>&lt;</code>3 files, clear approach)</li>
<li class="">Documentation updates</li>
<li class="">Cosmetic changes (formatting, renaming)</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-planning-process">The Planning Process<a href="#the-planning-process" class="hash-link" aria-label="Direct link to The Planning Process" title="Direct link to The Planning Process" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="1-create-a-planning-document">1. Create a Planning Document<a href="#1-create-a-planning-document" class="hash-link" aria-label="Direct link to 1. Create a Planning Document" title="Direct link to 1. Create a Planning Document" translate="no">​</a></h3>
<p>Create a file in the <code>planning/</code> directory (git-ignored for free iteration):</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#393A34"><span class="token comment" style="color:#999988;font-style:italic"># Example:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token function" style="color:#d73a49">touch</span><span class="token plain"> planning/my-feature-refactoring-plan.md</span><br></span></code></pre></div></div>
<p><strong>Note:</strong> The <code>planning/</code> directory is git-ignored, so you can iterate freely without polluting git history.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="2-use-the-planning-template">2. Use the Planning Template<a href="#2-use-the-planning-template" class="hash-link" aria-label="Direct link to 2. Use the Planning Template" title="Direct link to 2. Use the Planning Template" translate="no">​</a></h3>
<p>Every planning document should include:</p>
<div class="language-markdown codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-markdown codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#393A34"><span class="token title important punctuation" style="color:#393A34">#</span><span class="token title important"> &lt;Feature&gt; Refactoring Plan</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token bold punctuation" style="color:#393A34">**</span><span class="token bold content">Status</span><span class="token bold punctuation" style="color:#393A34">**</span><span class="token plain">: 🔄 PLANNING | 🚧 IN PROGRESS | ✅ COMPLETED | ❌ CANCELLED</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token bold punctuation" style="color:#393A34">**</span><span class="token bold content">Created</span><span class="token bold punctuation" style="color:#393A34">**</span><span class="token plain">: YYYY-MM-DD</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token bold punctuation" style="color:#393A34">**</span><span class="token bold content">Last Updated</span><span class="token bold punctuation" style="color:#393A34">**</span><span class="token plain">: YYYY-MM-DD</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token title important punctuation" style="color:#393A34">##</span><span class="token title important"> Problem Statement</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token list punctuation" style="color:#393A34">-</span><span class="token plain"> What&#x27;s the issue?</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token list punctuation" style="color:#393A34">-</span><span class="token plain"> Why does it need fixing?</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token list punctuation" style="color:#393A34">-</span><span class="token plain"> Current pain points</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token title important punctuation" style="color:#393A34">##</span><span class="token title important"> Proposed Solution</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token list punctuation" style="color:#393A34">-</span><span class="token plain"> High-level approach</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token list punctuation" style="color:#393A34">-</span><span class="token plain"> File structure (before/after)</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token list punctuation" style="color:#393A34">-</span><span class="token plain"> Module responsibilities</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token title important punctuation" style="color:#393A34">##</span><span class="token title important"> Migration Strategy</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token list punctuation" style="color:#393A34">-</span><span class="token plain"> Phase-by-phase breakdown</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token list punctuation" style="color:#393A34">-</span><span class="token plain"> File lifecycle (CREATE/MODIFY/DELETE/RENAME)</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token list punctuation" style="color:#393A34">-</span><span class="token plain"> Dependencies between phases</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token list punctuation" style="color:#393A34">-</span><span class="token plain"> Testing checkpoints</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token title important punctuation" style="color:#393A34">##</span><span class="token title important"> Risks &amp; Mitigation</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token list punctuation" style="color:#393A34">-</span><span class="token plain"> What could go wrong?</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token list punctuation" style="color:#393A34">-</span><span class="token plain"> How to prevent it?</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token list punctuation" style="color:#393A34">-</span><span class="token plain"> Rollback strategy</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token title important punctuation" style="color:#393A34">##</span><span class="token title important"> Success Criteria</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token list punctuation" style="color:#393A34">-</span><span class="token plain"> Measurable improvements</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token list punctuation" style="color:#393A34">-</span><span class="token plain"> Testing requirements</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token list punctuation" style="color:#393A34">-</span><span class="token plain"> Verification steps</span><br></span></code></pre></div></div>
<p>See <code>planning/README.md</code> for detailed template explanation.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="3-iterate-freely">3. Iterate Freely<a href="#3-iterate-freely" class="hash-link" aria-label="Direct link to 3. Iterate Freely" title="Direct link to 3. Iterate Freely" translate="no">​</a></h3>
<p>Since <code>planning/</code> is git-ignored:</p>
<ul>
<li class="">Draft multiple versions</li>
<li class="">Get AI assistance without commit pressure</li>
<li class="">Refine until the plan is solid</li>
<li class="">No need to clean up intermediate versions</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="4-implementation-phase">4. Implementation Phase<a href="#4-implementation-phase" class="hash-link" aria-label="Direct link to 4. Implementation Phase" title="Direct link to 4. Implementation Phase" translate="no">​</a></h3>
<p>Once plan is approved:</p>
<ul>
<li class="">Follow the phases defined in the plan</li>
<li class="">Test after each phase (don&#x27;t skip!)</li>
<li class="">Update plan if issues discovered</li>
<li class="">Track progress through phase status</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="5-after-completion">5. After Completion<a href="#5-after-completion" class="hash-link" aria-label="Direct link to 5. After Completion" title="Direct link to 5. After Completion" translate="no">​</a></h3>
<p><strong>Option A: Archive in docs/development/</strong>
If the plan has lasting value (successful pattern, reusable approach):</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">mv</span><span class="token plain"> planning/my-feature-refactoring-plan.md docs/development/</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token function" style="color:#d73a49">git</span><span class="token plain"> </span><span class="token function" style="color:#d73a49">add</span><span class="token plain"> docs/development/my-feature-refactoring-plan.md</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token function" style="color:#d73a49">git</span><span class="token plain"> commit </span><span class="token parameter variable" style="color:#36acaa">-m</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">&quot;docs: archive successful refactoring plan&quot;</span><br></span></code></pre></div></div>
<p><strong>Option B: Delete</strong>
If the plan served its purpose and code is the source of truth:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">rm</span><span class="token plain"> planning/my-feature-refactoring-plan.md</span><br></span></code></pre></div></div>
<p><strong>Option C: Keep locally (not committed)</strong>
For &quot;why we didn&#x27;t do X&quot; reference:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">mkdir</span><span class="token plain"> </span><span class="token parameter variable" style="color:#36acaa">-p</span><span class="token plain"> planning/archive</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token function" style="color:#d73a49">mv</span><span class="token plain"> planning/my-feature-refactoring-plan.md planning/archive/</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic"># Still git-ignored, just organized</span><br></span></code></pre></div></div>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="real-world-example">Real-World Example<a href="#real-world-example" class="hash-link" aria-label="Direct link to Real-World Example" title="Direct link to Real-World Example" translate="no">​</a></h2>
<p>The <strong>sensor/ package refactoring</strong> (Nov 2025) is a successful example:</p>
<p><strong>Before:</strong></p>
<ul>
<li class=""><code>sensor.py</code> - 2,574 lines, hard to navigate</li>
</ul>
<p><strong>After:</strong></p>
<ul>
<li class=""><code>sensor/</code> package with 5 focused modules</li>
<li class="">Each module <code>&lt;</code>800 lines</li>
<li class="">Clear separation of concerns</li>
</ul>
<p><strong>Process:</strong></p>
<ol>
<li class="">Created <code>planning/module-splitting-plan.md</code> (now in <code>docs/development/</code>)</li>
<li class="">Defined 6 phases with clear file lifecycle</li>
<li class="">Implemented phase by phase</li>
<li class="">Tested after each phase</li>
<li class="">Documented in AGENTS.md</li>
<li class="">Moved plan to <code>docs/development/</code> as reference</li>
</ol>
<p><strong>Key learnings:</strong></p>
<ul>
<li class="">Temporary <code>_impl.py</code> files avoid Python package conflicts</li>
<li class="">Test after EVERY phase (don&#x27;t accumulate changes)</li>
<li class="">Clear file lifecycle (CREATE/MODIFY/DELETE/RENAME)</li>
<li class="">Phase-by-phase approach enables safe rollback</li>
</ul>
<p><strong>Note:</strong> The complete module splitting plan was documented during implementation but has been superseded by the actual code structure.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="phase-by-phase-implementation">Phase-by-Phase Implementation<a href="#phase-by-phase-implementation" class="hash-link" aria-label="Direct link to Phase-by-Phase Implementation" title="Direct link to Phase-by-Phase Implementation" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="why-phases-matter">Why Phases Matter<a href="#why-phases-matter" class="hash-link" aria-label="Direct link to Why Phases Matter" title="Direct link to Why Phases Matter" translate="no">​</a></h3>
<p>Breaking refactorings into phases:</p>
<ul>
<li class="">✅ Enables testing after each change (catch bugs early)</li>
<li class="">✅ Allows rollback to last good state</li>
<li class="">✅ Makes progress visible</li>
<li class="">✅ Reduces cognitive load (focus on one thing)</li>
<li class="">❌ Takes more time (but worth it!)</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="phase-structure">Phase Structure<a href="#phase-structure" class="hash-link" aria-label="Direct link to Phase Structure" title="Direct link to Phase Structure" translate="no">​</a></h3>
<p>Each phase should:</p>
<ol>
<li class=""><strong>Have clear goal</strong> - What&#x27;s being changed?</li>
<li class=""><strong>Document file lifecycle</strong> - CREATE/MODIFY/DELETE/RENAME</li>
<li class=""><strong>Define success criteria</strong> - How to verify it worked?</li>
<li class=""><strong>Include testing steps</strong> - What to test?</li>
<li class=""><strong>Estimate time</strong> - Realistic time budget</li>
</ol>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="example-phase-documentation">Example Phase Documentation<a href="#example-phase-documentation" class="hash-link" aria-label="Direct link to Example Phase Documentation" title="Direct link to Example Phase Documentation" translate="no">​</a></h3>
<div class="language-markdown codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-markdown codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#393A34"><span class="token title important punctuation" style="color:#393A34">###</span><span class="token title important"> Phase 3: Extract Helper Functions (Session 3)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token bold punctuation" style="color:#393A34">**</span><span class="token bold content">Goal</span><span class="token bold punctuation" style="color:#393A34">**</span><span class="token plain">: Move pure utility functions to helpers.py</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token bold punctuation" style="color:#393A34">**</span><span class="token bold content">File Lifecycle</span><span class="token bold punctuation" style="color:#393A34">**</span><span class="token plain">:</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token list punctuation" style="color:#393A34">-</span><span class="token plain"> ✨ CREATE </span><span class="token code-snippet code keyword" style="color:#00009f">`sensor/helpers.py`</span><span class="token plain"> (utility functions)</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token list punctuation" style="color:#393A34">-</span><span class="token plain"> ✏️ MODIFY </span><span class="token code-snippet code keyword" style="color:#00009f">`sensor/core.py`</span><span class="token plain"> (import from helpers.py)</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token bold punctuation" style="color:#393A34">**</span><span class="token bold content">Steps</span><span class="token bold punctuation" style="color:#393A34">**</span><span class="token plain">:</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token list punctuation" style="color:#393A34">1.</span><span class="token plain"> Create sensor/helpers.py</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token list punctuation" style="color:#393A34">2.</span><span class="token plain"> Move pure functions (no state, no self)</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token list punctuation" style="color:#393A34">3.</span><span class="token plain"> Add comprehensive docstrings</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token list punctuation" style="color:#393A34">4.</span><span class="token plain"> Update imports in core.py</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token bold punctuation" style="color:#393A34">**</span><span class="token bold content">Estimated time</span><span class="token bold punctuation" style="color:#393A34">**</span><span class="token plain">: 45 minutes</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token bold punctuation" style="color:#393A34">**</span><span class="token bold content">Success criteria</span><span class="token bold punctuation" style="color:#393A34">**</span><span class="token plain">:</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token list punctuation" style="color:#393A34">-</span><span class="token plain"> ✅ All pure functions moved</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token list punctuation" style="color:#393A34">-</span><span class="token plain"> ✅ </span><span class="token code-snippet code keyword" style="color:#00009f">`./scripts/lint-check`</span><span class="token plain"> passes</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token list punctuation" style="color:#393A34">-</span><span class="token plain"> ✅ HA starts successfully</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token list punctuation" style="color:#393A34">-</span><span class="token plain"> ✅ All entities work correctly</span><br></span></code></pre></div></div>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="testing-strategy">Testing Strategy<a href="#testing-strategy" class="hash-link" aria-label="Direct link to Testing Strategy" title="Direct link to Testing Strategy" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="after-each-phase">After Each Phase<a href="#after-each-phase" class="hash-link" aria-label="Direct link to After Each Phase" title="Direct link to After Each Phase" translate="no">​</a></h3>
<p>Minimum testing checklist:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#393A34"><span class="token comment" style="color:#999988;font-style:italic"># 1. Linting passes</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">./scripts/lint-check</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic"># 2. Home Assistant starts</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">./scripts/develop</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic"># Watch for startup errors in logs</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic"># 3. Integration loads</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic"># Check: Settings → Devices &amp; Services → Tibber Prices</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic"># Verify: All entities appear</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic"># 4. Basic functionality</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic"># Test: Data updates without errors</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic"># Check: Entity states update correctly</span><br></span></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="comprehensive-testing-final-phase">Comprehensive Testing (Final Phase)<a href="#comprehensive-testing-final-phase" class="hash-link" aria-label="Direct link to Comprehensive Testing (Final Phase)" title="Direct link to Comprehensive Testing (Final Phase)" translate="no">​</a></h3>
<p>After completing all phases:</p>
<ul>
<li class="">Test all entities (sensors, binary sensors)</li>
<li class="">Test configuration flow (add/modify/remove)</li>
<li class="">Test options flow (change settings)</li>
<li class="">Test services (custom service calls)</li>
<li class="">Test error handling (disconnect API, invalid data)</li>
<li class="">Test caching (restart HA, verify cache loads)</li>
<li class="">Test time-based updates (quarter-hour refresh)</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="common-pitfalls">Common Pitfalls<a href="#common-pitfalls" class="hash-link" aria-label="Direct link to Common Pitfalls" title="Direct link to Common Pitfalls" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="-skip-planning-for-large-changes">❌ Skip Planning for Large Changes<a href="#-skip-planning-for-large-changes" class="hash-link" aria-label="Direct link to ❌ Skip Planning for Large Changes" title="Direct link to ❌ Skip Planning for Large Changes" translate="no">​</a></h3>
<p><strong>Problem:</strong> &quot;This seems straightforward, I&#x27;ll just start coding...&quot;</p>
<p><strong>Result:</strong> Halfway through, realize the approach doesn&#x27;t work. Wasted time.</p>
<p><strong>Solution:</strong> If unsure, spend 30 minutes on a rough plan. Better to plan and discard than get stuck.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="-implement-all-phases-at-once">❌ Implement All Phases at Once<a href="#-implement-all-phases-at-once" class="hash-link" aria-label="Direct link to ❌ Implement All Phases at Once" title="Direct link to ❌ Implement All Phases at Once" translate="no">​</a></h3>
<p><strong>Problem:</strong> &quot;I&#x27;ll do all phases, then test everything...&quot;</p>
<p><strong>Result:</strong> 10+ files changed, 2000+ lines modified, hard to debug if something breaks.</p>
<p><strong>Solution:</strong> Test after EVERY phase. Commit after each successful phase.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="-forget-to-update-documentation">❌ Forget to Update Documentation<a href="#-forget-to-update-documentation" class="hash-link" aria-label="Direct link to ❌ Forget to Update Documentation" title="Direct link to ❌ Forget to Update Documentation" translate="no">​</a></h3>
<p><strong>Problem:</strong> Code is refactored, but AGENTS.md and docs/ still reference old structure.</p>
<p><strong>Result:</strong> AI/humans get confused by outdated documentation.</p>
<p><strong>Solution:</strong> Include &quot;Documentation Phase&quot; at the end of every refactoring plan.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="-ignore-the-planning-directory">❌ Ignore the Planning Directory<a href="#-ignore-the-planning-directory" class="hash-link" aria-label="Direct link to ❌ Ignore the Planning Directory" title="Direct link to ❌ Ignore the Planning Directory" translate="no">​</a></h3>
<p><strong>Problem:</strong> &quot;I&#x27;ll just create the plan in docs/ directly...&quot;</p>
<p><strong>Result:</strong> Git history polluted with draft iterations, or pressure to &quot;commit something&quot; too early.</p>
<p><strong>Solution:</strong> Always use <code>planning/</code> for work-in-progress. Move to <code>docs/</code> only when done.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="integration-with-ai-development">Integration with AI Development<a href="#integration-with-ai-development" class="hash-link" aria-label="Direct link to Integration with AI Development" title="Direct link to Integration with AI Development" translate="no">​</a></h2>
<p>This project uses AI heavily (GitHub Copilot, Claude). The planning process supports AI development:</p>
<p><strong>AI reads from:</strong></p>
<ul>
<li class=""><code>AGENTS.md</code> - Long-term memory, patterns, conventions (AI-focused)</li>
<li class=""><code>docs/development/</code> - Human-readable guides (human-focused)</li>
<li class=""><code>planning/</code> - Active refactoring plans (shared context)</li>
</ul>
<p><strong>AI updates:</strong></p>
<ul>
<li class=""><code>AGENTS.md</code> - When patterns change</li>
<li class=""><code>planning/*.md</code> - During refactoring implementation</li>
<li class=""><code>docs/development/</code> - After successful completion</li>
</ul>
<p><strong>Why separate AGENTS.md and docs/development/?</strong></p>
<ul>
<li class=""><code>AGENTS.md</code>: Technical, comprehensive, AI-optimized</li>
<li class=""><code>docs/development/</code>: Practical, focused, human-optimized</li>
<li class="">Both stay in sync but serve different audiences</li>
</ul>
<p>See <a href="https://github.com/jpawlowski/hass.tibber_prices/blob/v0.20.0/AGENTS.md" target="_blank" rel="noopener noreferrer" class="">AGENTS.md</a> section &quot;Planning Major Refactorings&quot; for AI-specific guidance.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="tools-and-resources">Tools and Resources<a href="#tools-and-resources" class="hash-link" aria-label="Direct link to Tools and Resources" title="Direct link to Tools and Resources" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="planning-directory">Planning Directory<a href="#planning-directory" class="hash-link" aria-label="Direct link to Planning Directory" title="Direct link to Planning Directory" translate="no">​</a></h3>
<ul>
<li class=""><code>planning/</code> - Git-ignored workspace for drafts</li>
<li class=""><code>planning/README.md</code> - Detailed planning documentation</li>
<li class=""><code>planning/*.md</code> - Active refactoring plans</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="example-plans">Example Plans<a href="#example-plans" class="hash-link" aria-label="Direct link to Example Plans" title="Direct link to Example Plans" translate="no">​</a></h3>
<ul>
<li class=""><code>docs/development/module-splitting-plan.md</code> - ✅ Completed, archived</li>
<li class=""><code>planning/config-flow-refactoring-plan.md</code> - 🔄 Planned (1013 lines → 4 modules)</li>
<li class=""><code>planning/binary-sensor-refactoring-plan.md</code> - 🔄 Planned (644 lines → 4 modules)</li>
<li class=""><code>planning/coordinator-refactoring-plan.md</code> - 🔄 Planned (1446 lines, high complexity)</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="helper-scripts">Helper Scripts<a href="#helper-scripts" class="hash-link" aria-label="Direct link to Helper Scripts" title="Direct link to Helper Scripts" translate="no">​</a></h3>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#393A34"><span class="token plain">./scripts/lint-check </span><span class="token comment" style="color:#999988;font-style:italic"># Verify code quality</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">./scripts/develop </span><span class="token comment" style="color:#999988;font-style:italic"># Start HA for testing</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">./scripts/lint </span><span class="token comment" style="color:#999988;font-style:italic"># Auto-fix issues</span><br></span></code></pre></div></div>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="faq">FAQ<a href="#faq" class="hash-link" aria-label="Direct link to FAQ" title="Direct link to FAQ" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="q-when-should-i-create-a-plan-vs-just-start-coding">Q: When should I create a plan vs. just start coding?<a href="#q-when-should-i-create-a-plan-vs-just-start-coding" class="hash-link" aria-label="Direct link to Q: When should I create a plan vs. just start coding?" title="Direct link to Q: When should I create a plan vs. just start coding?" translate="no">​</a></h3>
<p><strong>A:</strong> If you&#x27;re asking this question, you probably need a plan. 😊</p>
<p>Simple rule: If you can&#x27;t describe the entire change in 3 sentences, create a plan.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="q-how-detailed-should-the-plan-be">Q: How detailed should the plan be?<a href="#q-how-detailed-should-the-plan-be" class="hash-link" aria-label="Direct link to Q: How detailed should the plan be?" title="Direct link to Q: How detailed should the plan be?" translate="no">​</a></h3>
<p><strong>A:</strong> Detailed enough to execute without major surprises, but not a line-by-line script.</p>
<p>Good plan level:</p>
<ul>
<li class="">Lists all files affected (CREATE/MODIFY/DELETE)</li>
<li class="">Defines phases with clear boundaries</li>
<li class="">Includes testing strategy</li>
<li class="">Estimates time per phase</li>
</ul>
<p>Too detailed:</p>
<ul>
<li class="">Exact code snippets for every change</li>
<li class="">Line-by-line instructions</li>
</ul>
<p>Too vague:</p>
<ul>
<li class="">&quot;Refactor sensor.py to be better&quot;</li>
<li class="">No phase breakdown</li>
<li class="">No testing strategy</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="q-what-if-the-plan-changes-during-implementation">Q: What if the plan changes during implementation?<a href="#q-what-if-the-plan-changes-during-implementation" class="hash-link" aria-label="Direct link to Q: What if the plan changes during implementation?" title="Direct link to Q: What if the plan changes during implementation?" translate="no">​</a></h3>
<p><strong>A:</strong> Update the plan! Planning documents are living documents.</p>
<p>If you discover:</p>
<ul>
<li class="">Better approach → Update &quot;Proposed Solution&quot;</li>
<li class="">More phases needed → Add to &quot;Migration Strategy&quot;</li>
<li class="">New risks → Update &quot;Risks &amp; Mitigation&quot;</li>
</ul>
<p>Document WHY the plan changed (helps future refactorings).</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="q-should-every-refactoring-follow-this-process">Q: Should every refactoring follow this process?<a href="#q-should-every-refactoring-follow-this-process" class="hash-link" aria-label="Direct link to Q: Should every refactoring follow this process?" title="Direct link to Q: Should every refactoring follow this process?" translate="no">​</a></h3>
<p><strong>A:</strong> No! Use judgment:</p>
<ul>
<li class=""><strong>Small changes (<code>&lt;</code>100 lines, clear approach)</strong>: Just do it, no plan needed</li>
<li class=""><strong>Medium changes (unclear scope)</strong>: Write rough outline, refine if needed</li>
<li class=""><strong>Large changes (&gt;500 lines, &gt;5 files)</strong>: Full planning process</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="q-how-do-i-know-when-a-refactoring-is-successful">Q: How do I know when a refactoring is successful?<a href="#q-how-do-i-know-when-a-refactoring-is-successful" class="hash-link" aria-label="Direct link to Q: How do I know when a refactoring is successful?" title="Direct link to Q: How do I know when a refactoring is successful?" translate="no">​</a></h3>
<p><strong>A:</strong> Check the &quot;Success Criteria&quot; from your plan:</p>
<p>Typical criteria:</p>
<ul>
<li class="">✅ All linting checks pass</li>
<li class="">✅ HA starts without errors</li>
<li class="">✅ All entities functional</li>
<li class="">✅ No regressions (existing features work)</li>
<li class="">✅ Code easier to understand/modify</li>
<li class="">✅ Documentation updated</li>
</ul>
<p>If you can&#x27;t tick all boxes, the refactoring isn&#x27;t done.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="summary">Summary<a href="#summary" class="hash-link" aria-label="Direct link to Summary" title="Direct link to Summary" translate="no">​</a></h2>
<p><strong>Key takeaways:</strong></p>
<ol>
<li class=""><strong>Plan when scope is unclear</strong> (&gt;500 lines, &gt;5 files, breaking changes)</li>
<li class=""><strong>Use planning/ directory</strong> for free iteration (git-ignored)</li>
<li class=""><strong>Work in phases</strong> and test after each phase</li>
<li class=""><strong>Document file lifecycle</strong> (CREATE/MODIFY/DELETE/RENAME)</li>
<li class=""><strong>Update documentation</strong> after completion (AGENTS.md, docs/)</li>
<li class=""><strong>Archive or delete</strong> plan after implementation</li>
</ol>
<p><strong>Remember:</strong> Good planning prevents half-finished refactorings and makes rollback easier when things go wrong.</p>
<hr>
<p><strong>Next steps:</strong></p>
<ul>
<li class="">Read <code>planning/README.md</code> for detailed template</li>
<li class="">Check <code>docs/development/module-splitting-plan.md</code> for real example</li>
<li class="">Browse <code>planning/</code> for active refactoring plans</li>
</ul></div><footer class="theme-doc-footer docusaurus-mt-lg"><div class="row margin-top--sm theme-doc-footer-edit-meta-row"><div class="col noPrint_WFHX"><a href="https://github.com/jpawlowski/hass.tibber_prices/tree/main/docs/developer/docs/refactoring-guide.md" target="_blank" rel="noopener noreferrer" class="theme-edit-this-page"><svg fill="currentColor" height="20" width="20" viewBox="0 0 40 40" class="iconEdit_Z9Sw" aria-hidden="true"><g><path d="m34.5 11.7l-3 3.1-6.3-6.3 3.1-3q0.5-0.5 1.2-0.5t1.1 0.5l3.9 3.9q0.5 0.4 0.5 1.1t-0.5 1.2z m-29.5 17.1l18.4-18.5 6.3 6.3-18.4 18.4h-6.3v-6.2z"></path></g></svg>Edit this page</a></div><div class="col lastUpdated_JAkA"><span class="theme-last-updated">Last updated<!-- --> on <b><time datetime="2025-12-06T01:37:06.000Z" itemprop="dateModified">Dec 6, 2025</time></b></span></div></div></footer></article><nav class="docusaurus-mt-lg pagination-nav" aria-label="Docs pages"><a class="pagination-nav__link pagination-nav__link--prev" href="/hass.tibber_prices/developer/period-calculation-theory"><div class="pagination-nav__sublabel">Previous</div><div class="pagination-nav__label">Period Calculation Theory</div></a><a class="pagination-nav__link pagination-nav__link--next" href="/hass.tibber_prices/developer/performance"><div class="pagination-nav__sublabel">Next</div><div class="pagination-nav__label">Performance Optimization</div></a></nav></div></div><div class="col col--3"><div class="tableOfContents_bqdL thin-scrollbar theme-doc-toc-desktop"><ul class="table-of-contents table-of-contents__left-border"><li><a href="#when-to-plan-a-refactoring" class="table-of-contents__link toc-highlight">When to Plan a Refactoring</a></li><li><a href="#the-planning-process" class="table-of-contents__link toc-highlight">The Planning Process</a><ul><li><a href="#1-create-a-planning-document" class="table-of-contents__link toc-highlight">1. Create a Planning Document</a></li><li><a href="#2-use-the-planning-template" class="table-of-contents__link toc-highlight">2. Use the Planning Template</a></li><li><a href="#3-iterate-freely" class="table-of-contents__link toc-highlight">3. Iterate Freely</a></li><li><a href="#4-implementation-phase" class="table-of-contents__link toc-highlight">4. Implementation Phase</a></li><li><a href="#5-after-completion" class="table-of-contents__link toc-highlight">5. After Completion</a></li></ul></li><li><a href="#real-world-example" class="table-of-contents__link toc-highlight">Real-World Example</a></li><li><a href="#phase-by-phase-implementation" class="table-of-contents__link toc-highlight">Phase-by-Phase Implementation</a><ul><li><a href="#why-phases-matter" class="table-of-contents__link toc-highlight">Why Phases Matter</a></li><li><a href="#phase-structure" class="table-of-contents__link toc-highlight">Phase Structure</a></li><li><a href="#example-phase-documentation" class="table-of-contents__link toc-highlight">Example Phase Documentation</a></li></ul></li><li><a href="#testing-strategy" class="table-of-contents__link toc-highlight">Testing Strategy</a><ul><li><a href="#after-each-phase" class="table-of-contents__link toc-highlight">After Each Phase</a></li><li><a href="#comprehensive-testing-final-phase" class="table-of-contents__link toc-highlight">Comprehensive Testing (Final Phase)</a></li></ul></li><li><a href="#common-pitfalls" class="table-of-contents__link toc-highlight">Common Pitfalls</a><ul><li><a href="#-skip-planning-for-large-changes" class="table-of-contents__link toc-highlight">❌ Skip Planning for Large Changes</a></li><li><a href="#-implement-all-phases-at-once" class="table-of-contents__link toc-highlight">❌ Implement All Phases at Once</a></li><li><a href="#-forget-to-update-documentation" class="table-of-contents__link toc-highlight">❌ Forget to Update Documentation</a></li><li><a href="#-ignore-the-planning-directory" class="table-of-contents__link toc-highlight">❌ Ignore the Planning Directory</a></li></ul></li><li><a href="#integration-with-ai-development" class="table-of-contents__link toc-highlight">Integration with AI Development</a></li><li><a href="#tools-and-resources" class="table-of-contents__link toc-highlight">Tools and Resources</a><ul><li><a href="#planning-directory" class="table-of-contents__link toc-highlight">Planning Directory</a></li><li><a href="#example-plans" class="table-of-contents__link toc-highlight">Example Plans</a></li><li><a href="#helper-scripts" class="table-of-contents__link toc-highlight">Helper Scripts</a></li></ul></li><li><a href="#faq" class="table-of-contents__link toc-highlight">FAQ</a><ul><li><a href="#q-when-should-i-create-a-plan-vs-just-start-coding" class="table-of-contents__link toc-highlight">Q: When should I create a plan vs. just start coding?</a></li><li><a href="#q-how-detailed-should-the-plan-be" class="table-of-contents__link toc-highlight">Q: How detailed should the plan be?</a></li><li><a href="#q-what-if-the-plan-changes-during-implementation" class="table-of-contents__link toc-highlight">Q: What if the plan changes during implementation?</a></li><li><a href="#q-should-every-refactoring-follow-this-process" class="table-of-contents__link toc-highlight">Q: Should every refactoring follow this process?</a></li><li><a href="#q-how-do-i-know-when-a-refactoring-is-successful" class="table-of-contents__link toc-highlight">Q: How do I know when a refactoring is successful?</a></li></ul></li><li><a href="#summary" class="table-of-contents__link toc-highlight">Summary</a></li></ul></div></div></div></div></main></div></div></div><footer class="theme-layout-footer footer footer--dark"><div class="container container-fluid"><div class="row footer__links"><div class="theme-layout-footer-column col footer__col"><div class="footer__title">Documentation</div><ul class="footer__items clean-list"><li class="footer__item"><a href="https://jpawlowski.github.io/hass.tibber_prices/user/" target="_blank" rel="noopener noreferrer" class="footer__link-item">User Guide<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a></li><li class="footer__item"><a class="footer__link-item" href="/hass.tibber_prices/developer/intro">Developer Guide</a></li></ul></div><div class="theme-layout-footer-column col footer__col"><div class="footer__title">Community</div><ul class="footer__items clean-list"><li class="footer__item"><a href="https://github.com/jpawlowski/hass.tibber_prices/issues" target="_blank" rel="noopener noreferrer" class="footer__link-item">GitHub Issues<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a></li><li class="footer__item"><a href="https://community.home-assistant.io/" target="_blank" rel="noopener noreferrer" class="footer__link-item">Home Assistant Community<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a></li></ul></div><div class="theme-layout-footer-column col footer__col"><div class="footer__title">More</div><ul class="footer__items clean-list"><li class="footer__item"><a href="https://github.com/jpawlowski/hass.tibber_prices" target="_blank" rel="noopener noreferrer" class="footer__link-item">GitHub<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a></li><li class="footer__item"><a href="https://github.com/jpawlowski/hass.tibber_prices/releases" target="_blank" rel="noopener noreferrer" class="footer__link-item">Release Notes<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a></li></ul></div></div><div class="footer__bottom text--center"><div class="footer__copyright">Not affiliated with Tibber AS. Community-maintained custom integration. Built with Docusaurus.</div></div></div></footer></div>
</body>
</html>
Reference in a new issue View git blame Copy permalink