Skip to content

Home Information - Your home, your data, organized.

Python

Still refactoring and tweaking documentation. WIP

Anthony Cassandra5ecc13edc310
diff --git a/.gitignore b/.gitignore
index cb2a5120..4811bc25 100644
--- a/.gitignore
+++ b/.gitignore
@@ -26,4 +26,4 @@ __pycache__/
/src/*txt
/*.html
-/docs/*.html
+/docs/**/*.html
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 45ab8482..9dd9bfcb 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -8,7 +8,7 @@ We welcome contributions! Follow these guidelines to get started.
The Home Information app's goal is to create a people-focused way to organize the various information needed to manage their homes. Home automation is great, but these systems tend to be device-focused instead of information-focused. They often add more complexity to your life rather than simplifying it. By creating a "single pane of glass" for all the information related to your home, we can begin fulfilling the promise of automation and technology and make managing your home, and your life, simpler.
-We've only just begun this journey. We've put some basic functonality in place to demonstrate its potential, but there are plenty of opportunities for improvements. Our [Road Map Page](RoadMap.md) shows just some of the future features we are thinking about.
+We've only just begun this journey. We've put some basic functonality in place to demonstrate its potential, but there are plenty of opportunities for improvements. Our [Road Map Page](docs/RoadMap.md) shows just some of the future features we are thinking about.
## How to Contribute
diff --git a/README.md b/README.md
index 7c54f6c5..6d24702d 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
# Home Information
-An application to visually organizes data about your home and the things in it. Add and position items on the screen and then attach notes, manuals, links, maintenance and repair histories or any other information for easy reference. Optionally integrates with security and home automation systems for a single view of all your house-related information.
+An application to visually organizes data about your home and the things in it. Add and position items on the screen and then attach notes, manuals, links, maintenance and repair histories or any other information for easy reference. Optionally integrates with security and home automation systems for a single view of all your home-related information.
<img src="docs/img/screenshot-kitchen.png" alt="Kitchen Example" width="250"> <img src="docs/img/screenshot-security.png" alt="Security Example" width="250"> <img src="docs/img/screenshot-cameras.png" alt="Camera Example" width="250">
diff --git a/docs/Development.md b/docs/Development.md
index 5490ea6a..b2b00d26 100644
--- a/docs/Development.md
+++ b/docs/Development.md
@@ -5,7 +5,6 @@
## Requirements and Dependencies
- Python 3.11 (or higher) - installed
-- Git - installed
- Redis - installed and running
See the [Dependencies Page](dev/Dependencies.md) if you want help installing those.
diff --git a/docs/Installation.md b/docs/Installation.md
index 89bf4c38..62e1cf5c 100644
--- a/docs/Installation.md
+++ b/docs/Installation.md
@@ -6,7 +6,8 @@
- Python 3 - installed
- Docker - installed and running
-- Git - installed
+
+See the [Dependencies Page](dev/Dependencies.md) if you want help installing those.
## Pre-install Considerations
@@ -113,7 +114,7 @@ Note: You could sign in without creating users by using the existing admin user.
#### Integrations
If you use any of the built-in integrations, so additional changes may be needed. See the
-[Integrations Page](docs/Integrations.md) for more details.
+[Integrations Page](Integrations.md) for more details.
## Troubleshooting
@@ -136,40 +137,3 @@ Requiring sign in depends on emails. If you have problems getting email working,
``` shell
HI_SUPPRESS_AUTHENTICATION="true"
```
-
-## Prerequisite Installs
-
-_Provided for convenience. May be outdated._
-
-### Python
-
-#### MacOS
-
-Get python 3.11 package and install from: [https://www.python.org/downloads/](https://www.python.org/downloads/)
-
-#### Ubuntu (GNU/Linux)
-
-``` shell
- sudo apt update && sudo apt upgrade
- sudo add-apt-repository ppa:deadsnakes/ppa
- sudo apt-get update
- apt list | grep python3.11
- sudo apt-get install python3.11
- sudo apt install python3.11-venv
-```
-
-### Docker
-
-#### MacOS
-
-See: [https://docs.docker.com/desktop/setup/install/mac-install/](https://docs.docker.com/desktop/setup/install/mac-install/)
-
-#### Ubuntu (GNU/Linux)
-
-``` shell
-sudo apt-get update
-sudo apt-get remove docker docker-engine docker.io
-sudo apt install docker.io
-sudo apt install docker-compose
-sudo systemctl start docker
-```
diff --git a/docs/Integrations.md b/docs/Integrations.md
index 4235b2bc..331b40f2 100644
--- a/docs/Integrations.md
+++ b/docs/Integrations.md
@@ -1,18 +1,31 @@
<img src="../src/hi/static/img/hi-logo-w-tagline-197x96.png" alt="Home Information Logo" width="128">
-ZZZ WIP
+# Integrations
+The current supported integrations are:
+- **Home Assistant** - General home automation platform for many types of devices and protocols. Requires installation and setup.
+- **ZoneMinder** - For managing security cameras with motion detection. Requires installation and setup.
-# Integrations
+To enable an integration, go to "Settings > Integrations > Add Integrations".
+
+When you enable one of these integrations, you will need to provide the necessary connection information, usually in the way of API endpoints and credentials.
-## ZoneMinder
+## Home Assistant (HAss)
+You will need install and set this up by following all their documentation. Start at the [Home Assistant Home Page](https://www.home-assistant.io/).
-### Permission Issues
+## ZoneMinder (ZM)
-zzzz
-If you are going to use the zoneminder integration, then viewing the camera video streams requires requires the server to authroize the browser to allow this off-site "origin". You will need to add the ZoneMinder URL to this envirornment variable.
+You will need install and set this up by following all their documentation. Start at the [ZoneMinder Home Page](https://zoneminder.com//).
+### CORS Issues
+
+If you are going to use the ZoneMinder integration, then viewing the camera video streams requires the server to authorize the browser to allow the ZoneMinder server to be an allowed off-site "origin". You will need to add the ZoneMinder URL to an envirornment variable to have Django server up the right headers to the browser:
+``` shell
export HI_EXTRA_CSP_URLS="${SCHEME}://${HOST}:${PORT}"
+```
+
+### HTTPS/SSL Issues
+
+Another potential issue with viewing the ZoneMinder camera streams can happen if your Home Information server runs trhrough HTTP and the ZoneMinder server streams are served thruogh HTTPS/SSL. Browsers prevent that due the security implications. This can be made worse if the ZoneMinder server is using a self-signed SSL cert (the default?). A workaround we found was to stand up an nginx server to proxy the HTTPS/SSL urls and serve them as plain HTTP in Home Information pages by changing the ZoneMinder setting "Portal URL".
-## Home Assistant
diff --git a/docs/dev/Architecture.md.html b/docs/dev/Architecture.md.html
deleted file mode 100644
index cf259884..00000000
--- a/docs/dev/Architecture.md.html
+++ /dev/null
@@ -1,251 +0,0 @@
-<!DOCTYPE html>
-<html>
- <head>
- <meta charset="utf-8">
- <meta name="viewport" content="width=device-width,initial-scale=1.0,user-scalable=no">
- <title>Architecture.md.html</title>
- <style>
- /* This CSS is originated from a following sites.
- https://github.com/magnetikonline/ghmarkdownrender */
- body {
- background: #fff;
- color: #333;
- font: 16px/1.5 -apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif,'Apple Color Emoji','Segoe UI Emoji','Segoe UI Symbol';
- width: 50em;
- border: 1px solid #ddd;
- outline: 1300px solid #fff;
- margin: 20px auto;
- padding: 40px;
- }
- #frame {
- border: 1px solid #ddd;
- border-radius: 3px;
- margin: 0 auto;
- width: 978px;
- }
- #markdown {
- padding: 45px;
- }
- #markdown > *:first-child {
- margin-top: 0;
- }
- #markdown > *:last-child {
- margin-bottom: 0;
- }
- h1,h2,h3,h4,h5,h6 {
- font-weight: 600;
- line-height: 1.25;
- margin: 24px 0 16px;
- padding: 0;
- }
- h1,h2 {
- padding-bottom: 0.3em;
- }
- h1 {
- border-bottom: 1px solid #eee;
- font-size: 2em;
- }
- h2 {
- border-bottom: 1px solid #eee;
- font-size: 1.5em;
- }
- h3 {
- font-size: 1.25em;
- }
- h4 {
- font-size: 1em;
- }
- h5 {
- font-size: 0.875em;
- }
- h6 {
- color: #777;
- font-size: 0.85em;
- }
- a {
- color: #4183c4;
- text-decoration: none;
- }
- a:hover {
- text-decoration: underline;
- }
- blockquote,dl,ol,p,pre,table,ul {
- margin: 0 0 16px;
- padding: 0;
- }
- blockquote {
- border-left: 0.25em solid #ddd;
- color: #777;
- padding: 0 1em;
- }
- blockquote > *:first-child {
- margin-top: 0;
- }
- blockquote > *:last-child {
- margin-bottom: 0
- }
- hr {
- background: #e7e7e7;
- border: 0;
- height: 0.25em;
- margin: 24px 0;
- overflow: hidden;
- padding: 0;
- }
- hr:before,
- hr:after {
- content: '';
- display: table;
- }
- hr:after {
- clear: both;
- }
- img {
- background: #fff;
- border: 0;
- box-sizing: content-box;
- max-width: 100%;
- }
- kbd {
- background: #fcfcfc;
- border-bottom-color: #bbb;
- border-radius: 3px;
- border: 1px solid #ccc;
- box-shadow: inset 0 -1px 0 #bbb;
- color: #555;
- display: inline-block;
- font: 11px/10px Consolas,'Liberation Mono',Menlo,Courier,monospace;
- padding: 3px 5px;
- vertical-align: middle;
- }
- ol,ul {
- padding-left: 2em;
- }
- ol ol,
- ol ul,
- ul ol,
- ul ul {
- margin-bottom: 0;
- margin-top: 0;
- }
- ol ol,
- ul ol {
- list-style-type: lower-roman;
- }
- li + li {
- margin-top: 0.25em;
- }
- li > p {
- margin-top: 16px;
- }
- table {
- border-collapse: collapse;
- border-spacing: 0;
- }
- table tr {
- background: #fff;
- border-top: 1px solid #ccc;
- }
- table tr:nth-child(2n) {
- background: #f8f8f8;
- }
- table th,
- table td {
- border: 1px solid #ddd;
- padding: 6px 13px;
- }
- table th {
- font-weight: bold;
- }
- code,pre,tt {
- font-family: Consolas,'Liberation Mono',Menlo,Courier,monospace;
- font-size: 12px;
- }
- code,tt {
- background: rgba(0,0,0,0.04);
- border-radius: 3px;
- font-size: 85%;
- margin: 0;
- padding: 0.2em 0;
- }
- code {
- white-space: nowrap;
- }
- code:before,
- code:after,
- tt:before,
- tt:after {
- content: '\\00a0';
- letter-spacing: -0.2em;
- }
- pre {
- background: #f7f7f7;
- border-radius: 3px;
- font-size: 85%;
- line-height: 1.45;
- overflow: auto;
- padding: 16px;
- }
- pre code,
- pre tt {
- background: transparent;
- border: 0;
- margin: 0;
- padding: 0;
- }
- pre > code {
- background: transparent;
- font-size: 100%;
- white-space: pre;
- }
- pre > code:before,
- pre > code:after {
- content: normal;
- }
- h1 code,h1 tt,
- h2 code,h2 tt,
- h3 code,h3 tt,
- h4 code,h4 tt,
- h5 code,h5 tt,
- h6 code,h6 tt {
- font-size: inherit;
- }
- .highlight { margin-bottom: 16px; }
- .pl-c { color: #969896; }
- .pl-c1,.pl-s .pl-v { color: #0086b3; }
- .pl-e,.pl-en { color: #795da3; }
- .pl-ent { color: #63a35c; }
- .pl-id { color: #b52a1d; }
- .pl-ii { background-color: #b52a1d;color: #f8f8f8; }
- .pl-k { color: #a71d5d; }
- .pl-mb { color: #333;font-weight: bold; }
- .pl-md { background-color: #ffecec;color: #bd2c00; }
- .pl-mdr { color: #795da3;font-weight: bold; }
- .pl-mh,.pl-mh .pl-en,.pl-ms { color: #1d3e81;font-weight: bold; }
- .pl-mi { color: #333;font-style: italic; }
- .pl-mi1 { background-color: #eaffea;color: #55a532; }
- .pl-ml { color: #693a17; }
- .pl-mo { color: #1d3e81; }
- .pl-mq { color: #008080; }
- .pl-s,.pl-pds,.pl-s .pl-pse .pl-s1,.pl-sr,.pl-sr .pl-cce,.pl-sr .pl-sre,.pl-sr .pl-sra { color: #183691; }
- .pl-smi,.pl-s .pl-s1 { color: #333; }
- .pl-sr .pl-cce { color: #63a35c;font-weight: bold; }
- .pl-v { color: #ed6a43; }
- #footer {
- color: #777;
- font-size: 11px;
- margin: 10px auto;
- text-align: right;
- white-space: nowrap;
- width: 978px;
- }
- </style>
- </head>
- <body>
- <p><a target="_blank" rel="noopener noreferrer" href="../../src/hi/static/img/hi-logo-w-tagline-197x96.png"><img src="../../src/hi/static/img/hi-logo-w-tagline-197x96.png" alt="Home Information Logo" width="128" style="max-width: 100%;"></a></p>
-<p><em>WORK IN PROGRESS</em></p>
-<div class="markdown-heading"><h1 class="heading-element">Architecture</h1><a id="user-content-architecture" class="anchor" aria-label="Permalink: Architecture" href="#architecture"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
-<p><a target="_blank" rel="noopener noreferrer" href="img/Architecture.png"><img src="img/Architecture.png" alt="Home Information Architecture" width="100%" style="max-width: 100%;"></a></p>
-
- </body>
-</html>
diff --git a/docs/dev/DataModel.md b/docs/dev/DataModel.md
index ad84bfd3..341f999c 100644
--- a/docs/dev/DataModel.md
+++ b/docs/dev/DataModel.md
@@ -1,22 +1,42 @@
<img src="../../src/hi/static/img/hi-logo-w-tagline-197x96.png" alt="Home Information Logo" width="128">
-_WORK IN PROGRESS_
-
# Data Model and Concepts
+## Entity
+
+- A physical or logical object with associated information.
+- Has zero or more attributes.
+- May or may not have sensors and controllers (from device integrations).
+- May or may not have (hidden) EntityState variables.
+- May or may not define other entities as delegates of its state.
+
+## EntityState
+
+- The hidden state of the entity/device that is sensed and/or controlled
+- A single entity may have zero or more states.
+
+## EntityStateDelegation
+
+- An EntityState of an entity may just be a proxy for another entity's state. e.g., A thermometer entity with a temperature state is a proxy for an area that is a room.
+- We use the terms 'delegate' and 'principal' for the entities involved in the relation.
+- Main use is to have the delegate's visual representation reflect the status of the principal's state.
+- May be one-to-one, one-to-many or many-to-one relationship.
+
## Location
-- Has an SVG image that defines the visual and coordinate space
-- Has zero or more entities
-- Entities indirectly associated through a position
-- Has zero or more collections
-- Collections indirectly associated through a position
-- Can have one or more locations, though 1 is most typical
+- Has an SVG image that defines the visual and coordinate space.
+- Has zero or more entities.
+- Entities optionally associated with a position.
+- Has zero or more collections.
+- Collections optionally associated with a position.
+- Can dfined one or more locations.
## LocationView
-- Defines a bounding box area of the location
-- Defines what is and is not visible
+- Associated with a Location.
+- Can define one or more Location Views for a Location.
+- Defines the view a bounding box area and rotation of the location SVG.
+- Defines what entities are and are not visible in this views.
- Defines the view context for sensors and controllers (info, control)
- ViewContext = { information, control }
@@ -26,67 +46,32 @@ _WORK IN PROGRESS_
- Helps define a consistent visual represenation for LocationView.
- Initially, Entity and Collection are the two concrete examples fof an LocationItem
-## Entity
+## EntityPosition / CollectionPosition
-- A physical or logical object
-- Has attributes
-- May or may not have a position in the location
-- May or may not have sensors and controller
-- May or may not have (hidden) state variables.
-- May or may not define a coverage Area for its sensors/controllers
+- For entities/collections positioned in a Location an visually appearing as an icon.
+- Defines the position, scale and rotation of the icon.
-## EntityState
-- The hidden state of the entity/device that is sensed and/or controlled
-- A single entity may have many states
+## EntityPath / CollectionPath
-## EntityStateDelegation
-
-- An EntityState of an entity may just be a proxy for another entity's state
-- e.g., A thermometer entity with a temperature state is a proxy for an area
-- We use the terms 'delegate' and 'principal' for the entities involved in the relation.
-- May be one-to-one, one-to-many or many-to-one relationship
+- For entities/collections positioned in a Location an visually appearing as an open or closed path.
## Device (runtime concept, not a DB model)
- An entity with at least one sensor or controller
-## Area (runtime concept, not a DB model)
-
-- An wrapper around Entity[type=area]
-- Usually defining a physical area that is being sensed and/or controlled
-- Defines special visual handling
-- Usually defined by SVG path
-- If has location/path, should be a (closed, convex) SVG path
-- Usually created to be proxied by entities/devices
-- Has implicit states that can be related to sensors and controller states
-- Clicking will invoke sensors/controllers defined for the area
-- Only shows for views it is associated with
-- Can be associated with mutliple views
-
## Sensor
-- Provides an observation value of a single entity state variable
-- Sensors and their states can only be created through integrations (not user editable)
+- Provides an observation value of a single entity's state variable.
+- Sensors and their states can only be created through integrations (not user editable).
## Controller
-- Provides an action to affect a single entity state variable
-- Controllers and their states can only be created through integrations (not user editable)
+- Provides an action to affect a single entity state variable.
+- Controllers and their states can only be created through integrations (not user editable).
## Collection
-- Defines a logical connection for a group of one or more entities
-- Collection of Entity for showing button and accessing list view
-- Often used to group non-positional items
-- Some entities in a collection may be unpositioned
-- Tools, appliances and devices are examples of unpositioned collections
-- Collections are tied to a view
-- Collection access buttons show at bottom
-- If has SVG position, can be overlayed on view
-- Inherits from view the view type (control, info)
-- Can be associated with mutliple views
-
-## Collection[type=zone]
-
-- Can provide way to group to get single button control of multiple controllers
+- Defines a logical connection for a group of one or more entities.
+- Some entities in a collection may be unpositioned e.g., tools, appliances and devices are potential examples of unpositioned collections
+- Collections may or may not be shown in a Location View (as a path).
diff --git a/docs/dev/Dependencies.md b/docs/dev/Dependencies.md
index 47d5bf99..23b93f8e 100644
--- a/docs/dev/Dependencies.md
+++ b/docs/dev/Dependencies.md
@@ -23,6 +23,23 @@ Get python 3.11 package and install from: [https://www.python.org/downloads/](ht
sudo apt install python3.11-venv
```
+
+### Docker
+
+#### MacOS
+
+See: [https://docs.docker.com/desktop/setup/install/mac-install/](https://docs.docker.com/desktop/setup/install/mac-install/)
+
+#### Ubuntu (GNU/Linux)
+
+``` shell
+sudo apt-get update
+sudo apt-get remove docker docker-engine docker.io
+sudo apt install docker.io
+sudo apt install docker-compose
+sudo systemctl start docker
+```
+
### Redis
#### MacOS
diff --git a/docs/dev/EntityStatus.md b/docs/dev/EntityStatus.md
index 09ae93ae..03df0c98 100644
--- a/docs/dev/EntityStatus.md
+++ b/docs/dev/EntityStatus.md
@@ -1,14 +1,12 @@
<img src="../../src/hi/static/img/hi-logo-w-tagline-197x96.png" alt="Home Information Logo" width="128">
-_WORK IN PROGRESS_
-
# Entity Status Display
All entity state variables are indirectly observed through a sensor, and all sensor values come from an integration, usually by polling an external service, device, file, etc. Integrations are responsible for normalizing sensor values and encapsulating them in a SensorResponse instance. The SensorResponseManager is the module that will receive these responses from integrations and will provide the latest status values and value histories to the various views. The SensorResponseManager also detects changes of status values and feed those into the alerting subsystem.
## Status (Visual) Display [Location View]
-A given Entity (SVG icon or SVG path) can alter its screen appearance based on the value of sensor readings for its underlying state variables. Mapping sensor responses to SVG appearance is the responsibility of the Status Display Helpers using StatusDisplayData. There are a few ways this can be done, depending on the underlying entity state type that the sensor is observing.
+A given Entity (SVG icon or SVG path) can alter its screen appearance based on the value of sensor readings for its underlying state variables. Mapping sensor responses to SVG appearance is the responsibility of the Status Display Helpers using `StatusDisplayData`. There are a few ways this can be done, depending on the underlying entity state type that the sensor is observing.
1. It can take the (normalized) sensor value directly and add it as a CSS class name to the displayed SVG file. This allows CSS rules to adjust the visual display for any well-known sensor values (hardcoded in CSS rules).
2. For well known sensor values, there can also be predefined/hard-coded alternative SVG icons.
@@ -16,7 +14,7 @@ A given Entity (SVG icon or SVG path) can alter its screen appearance based on t
## Value Decaying
-For some entity state types (and sensors), we not only want to display the current sensor value, but also represent the recent past values. For example, when motion is detected in an area, we want to highlight that, but after the motion event is over, we will want to visually show that it was "active" in the recent past. e.g., Active motion is shown as red, but over time decays to oranges then yellows when the motion is over.
+For some entity state types (and sensors), we not only want to display the current sensor value, but also visually represent the recent past values. For example, when motion is detected in an area, we want to highlight that, but after the motion event is over, we will want to visually show that it was "active" in the recent past. e.g., Active motion is shown as red, but over time decays to oranges then yellows when the motion is over.
## Multiple Sensors
@@ -24,11 +22,11 @@ The visual representation provided is always for an Entity, but an entity can ha
To achieve this, we define a default priority of the entity states and the highest priority state will be used. However, a single static priority order is too limiting for many use cases. Thus, we need to be able to support different priorties for different purposes. For example, we may want a climate control view and a security view of a defined area. In the former, we want the temperature sensor value to dictate the visual display, while in the latter, the motion sensor should have its value impacting the area's visual display.
-To allow some user control over the visuals from sensor values, each LocationView instance can have its location_view_type set to one of the enum values whicih will determine which EntityStateType value will take precedence for status displays. See hi.apps.location.enums.LocationViewType.
+To allow some user control over the visuals from sensor values, each LocationView instance can have its `location_view_type` set to one of the enum values whicih will determine which EntityStateType value will take precedence for status displays. See `hi.apps.location.enums.LocationViewType`.
## Client-Server Interactions to Refresh State Display
-The Javascript polling.js module polls the server for the latest sensor values for all entity states. The server fetches the latest sensor values via StatusDataHelper, computes their visual display using StatusDisplayData and then returns a generalized JSON dicttionary that maps css class names to a set of attribute name-value pairs to update. The original rendered HTML from the Django templates will make sure the proper entities have the proper class names and attribute values for this to work.
+The Javascript `polling.js` module polls the server for the latest sensor values for all entity states. The server fetches the latest sensor values via `StatusDataHelper`, computes their visual display using `StatusDisplayData` and then returns a generalized JSON dictionary that maps css class names to a set of attribute name-value pairs to update. The original rendered HTML from the Django templates will make sure the proper entities have the proper class names and attribute values for this to work.
-The polling.js module tries to be general and only deal with finding class names and updating attribute name-value pairs. This works for the SVG <g> aND <path> tags. However, there a few special case patterns needs for SELECT tags for controllers and <div> elements for the non-SVG display cases (e.g., viewing entity status in a Collection View or in a sttaus modal).
+The `polling.js` module tries to be general and only deal with finding class names and updating attribute name-value pairs. This works for the SVG `g` and `path` tags. However, there a few special case patterns needs for `select` tags for controllers and `div` elements for the non-SVG display cases (e.g., viewing entity status in a Collection View or in a sttaus modal).
diff --git a/docs/dev/EventsAlarmsAlerts.md b/docs/dev/EventsAlarmsAlerts.md
index b04c172a..36abd2d2 100644
--- a/docs/dev/EventsAlarmsAlerts.md
+++ b/docs/dev/EventsAlarmsAlerts.md
@@ -1,7 +1,5 @@
<img src="../../src/hi/static/img/hi-logo-w-tagline-197x96.png" alt="Home Information Logo" width="128">
-_WORK IN PROGRESS_
-
# Events, Alarms and Alerts
`SensorResponses` can create events for a user-defined set of rules.
diff --git a/docs/dev/Guidelines.md b/docs/dev/Guidelines.md
index 67c60d55..a74a6e19 100644
--- a/docs/dev/Guidelines.md
+++ b/docs/dev/Guidelines.md
@@ -2,6 +2,55 @@
# Development Guidelines
+## Code Organization and Conventions
+
+### Directories
+
+#### Top-level Directory
+
+- `src`: application source code (see below).
+- `deploy`: helper scripts and files for deploying and setting up the application.
+- `package`: extra items that need to be packaged up to support running trhe application in Docker.
+- `Makefile`: provides convenience wrappers around command for building, packaging and running.
+- `docs`: all documentation that suitable to be in markdown files.
+
+#### The `src` Directory
+
+- `hi`: entry point urls/views and some app-wide helper classes.
+- `hi/templates`: For top-level views and app-wide common base templates.
+- `hi/apps/${APPNAME}`: For normal application modules.
+- `hi/apps/${APPNAME}/edit`: For normal application modules.
+- `hi/apps/`: For normal application modules.
+- `hi/integrations`: Code for dealing with integration not related to a specific integration.
+- `hi/services/${SERVICENAME}`: Code for a particular integration. See the [Integrations Page](Integrations.md).
+- `hi/simulator`: The code for the separate simulator helper app. See the [Simulator Page](Simulator.md).
+- `hi/settings`: Django settings, including runtime population from environment variables.
+- `hi/requirements`: Python package dependencies.
+- `custom`: Custom user model and other general customizations.
+- `bin`: Helper scripts needed with the code to run inside a Docker container.
+
+### App Module Structure
+
+- `enums.py`: For enums related to the module.
+- `models.py`: For Django ORM models (by Django conventions).
+- `transient_models.py`: For (small-ish) non-ORM models that are not persisted.
+- `urls.py` - When module provides views.
+- `views.py` - Main views for module.
+- `views_mixin.py` - If there is common view functions needs.
+- `forms.py` - If any Django forms are using in views.
+- `${NAME}_manager.py` - If there is internal, persistent data the module provides, a singleton manager class is used.
+- `settings.py`: If app wants to provide user-controllable settings.
+- `monitors.py`: If app module needs a periodic background process.
+- `templates/${APPNAME}`: The apps templates. Also see the [Templates Page](Templates.md).
+- `apps.py`: Django-required module definition.
+- `admin.py`: For adding to Django admin console (by Django conventions).
+
+If a module provides views or functionality that is only applicable to edit mode, then an `edit` subdirectory is used with the same structure, e.g.,
+
+- `edit/urls.py` - UURLs if module provides edit-only views.
+- `edit/views.py` - Edit-only views for module.
+- etc.
+
## Coding Style
The project triued to adhere to PEP8 but we strongly disagree with the broadly accepted coding guidelines around spaces. Spaces are great visual delimiters and greatly enhance readability. The whitespace deviations we make to PEP8 are shown in this Flake8 config file (`ignore`).
@@ -28,10 +77,6 @@ max-line-length = 110
ignore = E129,D203,E201,E202,E203,E221,E231,E251,W293,W291,W391,W503
```
-## Code Organization
-
-_TBD_
-
## Testing Conventions
_TBD_
diff --git a/docs/dev/Integrations.md b/docs/dev/Integrations.md
index c80f16fe..5c0b82d2 100644
--- a/docs/dev/Integrations.md
+++ b/docs/dev/Integrations.md
@@ -1,7 +1,5 @@
<img src="../../src/hi/static/img/hi-logo-w-tagline-197x96.png" alt="Home Information Logo" width="128">
-_WORK IN PROGRESS_
-
# Integrations
- Each integration is a Django app in the `hi/services` directory.
diff --git a/docs/dev/Setup.md.html b/docs/dev/Setup.md.html
deleted file mode 100644
index 0dee6e65..00000000
--- a/docs/dev/Setup.md.html
+++ /dev/null
@@ -1,312 +0,0 @@
-<!DOCTYPE html>
-<html>
- <head>
- <meta charset="utf-8">
- <meta name="viewport" content="width=device-width,initial-scale=1.0,user-scalable=no">
- <title>Setup.md.html</title>
- <style>
- /* This CSS is originated from a following sites.
- https://github.com/magnetikonline/ghmarkdownrender */
- body {
- background: #fff;
- color: #333;
- font: 16px/1.5 -apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif,'Apple Color Emoji','Segoe UI Emoji','Segoe UI Symbol';
- width: 50em;
- border: 1px solid #ddd;
- outline: 1300px solid #fff;
- margin: 20px auto;
- padding: 40px;
- }
- #frame {
- border: 1px solid #ddd;
- border-radius: 3px;
- margin: 0 auto;
- width: 978px;
- }
- #markdown {
- padding: 45px;
- }
- #markdown > *:first-child {
- margin-top: 0;
- }
- #markdown > *:last-child {
- margin-bottom: 0;
- }
- h1,h2,h3,h4,h5,h6 {
- font-weight: 600;
- line-height: 1.25;
- margin: 24px 0 16px;
- padding: 0;
- }
- h1,h2 {
- padding-bottom: 0.3em;
- }
- h1 {
- border-bottom: 1px solid #eee;
- font-size: 2em;
- }
- h2 {
- border-bottom: 1px solid #eee;
- font-size: 1.5em;
- }
- h3 {
- font-size: 1.25em;
- }
- h4 {
- font-size: 1em;
- }
- h5 {
- font-size: 0.875em;
- }
- h6 {
- color: #777;
- font-size: 0.85em;
- }
- a {
- color: #4183c4;
- text-decoration: none;
- }
- a:hover {
- text-decoration: underline;
- }
- blockquote,dl,ol,p,pre,table,ul {
- margin: 0 0 16px;
- padding: 0;
- }
- blockquote {
- border-left: 0.25em solid #ddd;
- color: #777;
- padding: 0 1em;
- }
- blockquote > *:first-child {
- margin-top: 0;
- }
- blockquote > *:last-child {
- margin-bottom: 0
- }
- hr {
- background: #e7e7e7;
- border: 0;
- height: 0.25em;
- margin: 24px 0;
- overflow: hidden;
- padding: 0;
- }
- hr:before,
- hr:after {
- content: '';
- display: table;
- }
- hr:after {
- clear: both;
- }
- img {
- background: #fff;
- border: 0;
- box-sizing: content-box;
- max-width: 100%;
- }
- kbd {
- background: #fcfcfc;
- border-bottom-color: #bbb;
- border-radius: 3px;
- border: 1px solid #ccc;
- box-shadow: inset 0 -1px 0 #bbb;
- color: #555;
- display: inline-block;
- font: 11px/10px Consolas,'Liberation Mono',Menlo,Courier,monospace;
- padding: 3px 5px;
- vertical-align: middle;
- }
- ol,ul {
- padding-left: 2em;
- }
- ol ol,
- ol ul,
- ul ol,
- ul ul {
- margin-bottom: 0;
- margin-top: 0;
- }
- ol ol,
- ul ol {
- list-style-type: lower-roman;
- }
- li + li {
- margin-top: 0.25em;
- }
- li > p {
- margin-top: 16px;
- }
- table {
- border-collapse: collapse;
- border-spacing: 0;
- }
- table tr {
- background: #fff;
- border-top: 1px solid #ccc;
- }
- table tr:nth-child(2n) {
- background: #f8f8f8;
- }
- table th,
- table td {
- border: 1px solid #ddd;
- padding: 6px 13px;
- }
- table th {
- font-weight: bold;
- }
- code,pre,tt {
- font-family: Consolas,'Liberation Mono',Menlo,Courier,monospace;
- font-size: 12px;
- }
- code,tt {
- background: rgba(0,0,0,0.04);
- border-radius: 3px;
- font-size: 85%;
- margin: 0;
- padding: 0.2em 0;
- }
- code {
- white-space: nowrap;
- }
- code:before,
- code:after,
- tt:before,
- tt:after {
- content: '\\00a0';
- letter-spacing: -0.2em;
- }
- pre {
- background: #f7f7f7;
- border-radius: 3px;
- font-size: 85%;
- line-height: 1.45;
- overflow: auto;
- padding: 16px;
- }
- pre code,
- pre tt {
- background: transparent;
- border: 0;
- margin: 0;
- padding: 0;
- }
- pre > code {
- background: transparent;
- font-size: 100%;
- white-space: pre;
- }
- pre > code:before,
- pre > code:after {
- content: normal;
- }
- h1 code,h1 tt,
- h2 code,h2 tt,
- h3 code,h3 tt,
- h4 code,h4 tt,
- h5 code,h5 tt,
- h6 code,h6 tt {
- font-size: inherit;
- }
- .highlight { margin-bottom: 16px; }
- .pl-c { color: #969896; }
- .pl-c1,.pl-s .pl-v { color: #0086b3; }
- .pl-e,.pl-en { color: #795da3; }
- .pl-ent { color: #63a35c; }
- .pl-id { color: #b52a1d; }
- .pl-ii { background-color: #b52a1d;color: #f8f8f8; }
- .pl-k { color: #a71d5d; }
- .pl-mb { color: #333;font-weight: bold; }
- .pl-md { background-color: #ffecec;color: #bd2c00; }
- .pl-mdr { color: #795da3;font-weight: bold; }
- .pl-mh,.pl-mh .pl-en,.pl-ms { color: #1d3e81;font-weight: bold; }
- .pl-mi { color: #333;font-style: italic; }
- .pl-mi1 { background-color: #eaffea;color: #55a532; }
- .pl-ml { color: #693a17; }
- .pl-mo { color: #1d3e81; }
- .pl-mq { color: #008080; }
- .pl-s,.pl-pds,.pl-s .pl-pse .pl-s1,.pl-sr,.pl-sr .pl-cce,.pl-sr .pl-sre,.pl-sr .pl-sra { color: #183691; }
- .pl-smi,.pl-s .pl-s1 { color: #333; }
- .pl-sr .pl-cce { color: #63a35c;font-weight: bold; }
- .pl-v { color: #ed6a43; }
- #footer {
- color: #777;
- font-size: 11px;
- margin: 10px auto;
- text-align: right;
- white-space: nowrap;
- width: 978px;
- }
- </style>
- </head>
- <body>
- <p><a target="_blank" rel="noopener noreferrer" href="../../src/hi/static/img/hi-logo-w-tagline-197x96.png"><img src="../../src/hi/static/img/hi-logo-w-tagline-197x96.png" alt="Home Information Logo" width="128" style="max-width: 100%;"></a></p>
-<div class="markdown-heading"><h1 class="heading-element">Development Setup</h1><a id="user-content-development-setup" class="anchor" aria-label="Permalink: Development Setup" href="#development-setup"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
-<div class="markdown-heading"><h2 class="heading-element">Fork the Repository</h2><a id="user-content-fork-the-repository" class="anchor" aria-label="Permalink: Fork the Repository" href="#fork-the-repository"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
-<ul>
-<li>Go to the main repository on GitHub: <a href="https://github.com/cassandra/home-information">https://github.com/cassandra/home-information</a>
-</li>
-<li>Click the "Fork" button in the upper-right corner.</li>
-<li>This creates a copy of the repository in the your GitHub account (keep same name if you can for simplicity).</li>
-<li>The forked repo will be located at <a href="https://github.com/$%7BYOURUSERNAME%7D/home-information.git">https://github.com/${YOURUSERNAME}/home-information.git</a> (if you kept the same repo name).</li>
-</ul>
-<div class="markdown-heading"><h2 class="heading-element">Local Repository Setup</h2><a id="user-content-local-repository-setup" class="anchor" aria-label="Permalink: Local Repository Setup" href="#local-repository-setup"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
-<p>Decide where you want to download the code to (adjust the following):</p>
-<div class="highlight highlight-source-shell"><pre>PROJ_DIR=<span class="pl-s"><span class="pl-pds">"</span><span class="pl-smi">${HOME}</span>/proj<span class="pl-pds">"</span></span>
-mkdir -p <span class="pl-smi">$PROJ_DIR</span>
-<span class="pl-c1">cd</span> <span class="pl-smi">$PROJ_DIR</span></pre></div>
-<p>Clone your fork to your local development envirnoment:</p>
-<div class="highlight highlight-source-shell"><pre>git clone https://github.com/<span class="pl-smi">${YOURUSERNAME}</span>/home-information.git
-
-<span class="pl-c"><span class="pl-c">#</span> Or use the SSH URL if you have SSH keys set up:</span>
-git clone [email protected]:<span class="pl-smi">${YOURUSERNAME}</span>/home-information.git</pre></div>
-<p>Add the original repo as "upstream":</p>
-<div class="highlight highlight-source-shell"><pre>git remote add upstream https://github.com/cassandra/home-information.git
-
-<span class="pl-c"><span class="pl-c">#</span> Or the SSH URL:</span>
-git remote add upstream [email protected]:<span class="pl-smi">${YOURUSERNAME}</span>/home-information.git</pre></div>
-<p>Verfy everything is set up properly:</p>
-<div class="highlight highlight-source-shell"><pre>git remote -v
-
-<span class="pl-c"><span class="pl-c">#</span> Expect</span>
-origin https://github.com/<span class="pl-smi">${YOURUSERNAME}</span>/home-information.git (fetch)
-origin https://github.com/<span class="pl-smi">${YOURUSERNAME}</span>/home-information.git (push)
-upstream https://github.com/cassandra/home-information.git (fetch)
-upstream https://github.com/cassandra/home-information.git (push)</pre></div>
-<div class="markdown-heading"><h2 class="heading-element">Environment Setup</h2><a id="user-content-environment-setup" class="anchor" aria-label="Permalink: Environment Setup" href="#environment-setup"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
-<p>Generate the environment variable file and review with the command below. The file will contain sensitive secrets and are stored in a <code>.private</code> directory. Also note that administrative credentials created during this next step.</p>
-<div class="highlight highlight-source-shell"><pre>make env-build-dev</pre></div>
-<p>This generates an environment variable file that we "source" before running:</p>
-<pre><code>$PROJ_DIR/.private/env/development.sh
-</code></pre>
-<p>This <code>.private</code> directory and its files should not be checked into the code repository. There is an existing <code>.gitignore</code> entry to prevent this. The adminstrative credentials generated can also be seen in that file.</p>
-<p>Next, create the Python virtual environment.</p>
-<div class="highlight highlight-source-shell"><pre><span class="pl-c1">cd</span> <span class="pl-smi">$PROJ_DIR</span>
-python3.11 -m venv venv</pre></div>
-<p>Now source the environment and virtual environment with this convenience script:</p>
-<div class="highlight highlight-source-shell"><pre><span class="pl-c1">.</span> ./init-env-dev.sh</pre></div>
-<p>In the future, just source'ing this script is all you need to set things up for development (virtual env and env vars).</p>
-<p>Next, install all the app's required Python packages (make sure you are in the virtual env).</p>
-<div class="highlight highlight-source-shell"><pre>pip install -r src/hi/requirements/development.txt</pre></div>
-<div class="markdown-heading"><h3 class="heading-element">App and Database Initializations</h3><a id="user-content-app-and-database-initializations" class="anchor" aria-label="Permalink: App and Database Initializations" href="#app-and-database-initializations"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
-<p>Initialize the database and add the admin users and groups.</p>
-<div class="highlight highlight-source-shell"><pre><span class="pl-c1">cd</span> <span class="pl-smi">$PROJ_DIR</span>
-<span class="pl-c1">cd</span> src
-./manage.py check
-./manage.py migrate
-./manage.py hi_createsuperuser
-./manage.py hi_creategroups</pre></div>
-<div class="markdown-heading"><h3 class="heading-element">Running</h3><a id="user-content-running" class="anchor" aria-label="Permalink: Running" href="#running"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
-<div class="highlight highlight-source-shell"><pre>./manage.py runserver</pre></div>
-<p>Then, visit: <a href="http://127.0.0.1:8411" rel="nofollow">http://127.0.0.1:8411</a> to access the app.</p>
-<p>If you want to familiarize yourself with how to use the app before diving inot the code, see the <a href="GettingStarted.md">Getting Started Page</a>.</p>
-<p>A look through these docs might also be a good starting point:</p>
-<ul>
-<li><a href="DataModel.md">Data Model</a></li>
-<li><a href="Architecture.md">Architecture</a></li>
-</ul>
-
- </body>
-</html>
diff --git a/docs/dev/Templates.md b/docs/dev/Templates.md
index f1d3bcf6..02ea9418 100644
--- a/docs/dev/Templates.md
+++ b/docs/dev/Templates.md
@@ -1,7 +1,5 @@
<img src="../../src/hi/static/img/hi-logo-w-tagline-197x96.png" alt="Home Information Logo" width="128">
-_WORK IN PROGRESS_
-
# Django Templates
## Template naming conventions
@@ -12,6 +10,8 @@ _WORK IN PROGRESS_
- `email` - For email templates
- `svg` - for SVG files.
+For app modules that also define some separate "edit" views, they will be in the same structure, one level down in an `edit` subdirectory.
+
## The "Hi Grid" Template Structure
_TBD_
diff --git a/docs/dev/Workflow.md.html b/docs/dev/Workflow.md.html
deleted file mode 100644
index 889f68d6..00000000
--- a/docs/dev/Workflow.md.html
+++ /dev/null
@@ -1,374 +0,0 @@
-<!DOCTYPE html>
-<html>
- <head>
- <meta charset="utf-8">
- <meta name="viewport" content="width=device-width,initial-scale=1.0,user-scalable=no">
- <title>Workflow.md.html</title>
- <style>
- /* This CSS is originated from a following sites.
- https://github.com/magnetikonline/ghmarkdownrender */
- body {
- background: #fff;
- color: #333;
- font: 16px/1.5 -apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif,'Apple Color Emoji','Segoe UI Emoji','Segoe UI Symbol';
- width: 50em;
- border: 1px solid #ddd;
- outline: 1300px solid #fff;
- margin: 20px auto;
- padding: 40px;
- }
- #frame {
- border: 1px solid #ddd;
- border-radius: 3px;
- margin: 0 auto;
- width: 978px;
- }
- #markdown {
- padding: 45px;
- }
- #markdown > *:first-child {
- margin-top: 0;
- }
- #markdown > *:last-child {
- margin-bottom: 0;
- }
- h1,h2,h3,h4,h5,h6 {
- font-weight: 600;
- line-height: 1.25;
- margin: 24px 0 16px;
- padding: 0;
- }
- h1,h2 {
- padding-bottom: 0.3em;
- }
- h1 {
- border-bottom: 1px solid #eee;
- font-size: 2em;
- }
- h2 {
- border-bottom: 1px solid #eee;
- font-size: 1.5em;
- }
- h3 {
- font-size: 1.25em;
- }
- h4 {
- font-size: 1em;
- }
- h5 {
- font-size: 0.875em;
- }
- h6 {
- color: #777;
- font-size: 0.85em;
- }
- a {
- color: #4183c4;
- text-decoration: none;
- }
- a:hover {
- text-decoration: underline;
- }
- blockquote,dl,ol,p,pre,table,ul {
- margin: 0 0 16px;
- padding: 0;
- }
- blockquote {
- border-left: 0.25em solid #ddd;
- color: #777;
- padding: 0 1em;
- }
- blockquote > *:first-child {
- margin-top: 0;
- }
- blockquote > *:last-child {
- margin-bottom: 0
- }
- hr {
- background: #e7e7e7;
- border: 0;
- height: 0.25em;
- margin: 24px 0;
- overflow: hidden;
- padding: 0;
- }
- hr:before,
- hr:after {
- content: '';
- display: table;
- }
- hr:after {
- clear: both;
- }
- img {
- background: #fff;
- border: 0;
- box-sizing: content-box;
- max-width: 100%;
- }
- kbd {
- background: #fcfcfc;
- border-bottom-color: #bbb;
- border-radius: 3px;
- border: 1px solid #ccc;
- box-shadow: inset 0 -1px 0 #bbb;
- color: #555;
- display: inline-block;
- font: 11px/10px Consolas,'Liberation Mono',Menlo,Courier,monospace;
- padding: 3px 5px;
- vertical-align: middle;
- }
- ol,ul {
- padding-left: 2em;
- }
- ol ol,
- ol ul,
- ul ol,
- ul ul {
- margin-bottom: 0;
- margin-top: 0;
- }
- ol ol,
- ul ol {
- list-style-type: lower-roman;
- }
- li + li {
- margin-top: 0.25em;
- }
- li > p {
- margin-top: 16px;
- }
- table {
- border-collapse: collapse;
- border-spacing: 0;
- }
- table tr {
- background: #fff;
- border-top: 1px solid #ccc;
- }
- table tr:nth-child(2n) {
- background: #f8f8f8;
- }
- table th,
- table td {
- border: 1px solid #ddd;
- padding: 6px 13px;
- }
- table th {
- font-weight: bold;
- }
- code,pre,tt {
- font-family: Consolas,'Liberation Mono',Menlo,Courier,monospace;
- font-size: 12px;
- }
- code,tt {
- background: rgba(0,0,0,0.04);
- border-radius: 3px;
- font-size: 85%;
- margin: 0;
- padding: 0.2em 0;
- }
- code {
- white-space: nowrap;
- }
- code:before,
- code:after,
- tt:before,
- tt:after {
- content: '\\00a0';
- letter-spacing: -0.2em;
- }
- pre {
- background: #f7f7f7;
- border-radius: 3px;
- font-size: 85%;
- line-height: 1.45;
- overflow: auto;
- padding: 16px;
- }
- pre code,
- pre tt {
- background: transparent;
- border: 0;
- margin: 0;
- padding: 0;
- }
- pre > code {
- background: transparent;
- font-size: 100%;
- white-space: pre;
- }
- pre > code:before,
- pre > code:after {
- content: normal;
- }
- h1 code,h1 tt,
- h2 code,h2 tt,
- h3 code,h3 tt,
- h4 code,h4 tt,
- h5 code,h5 tt,
- h6 code,h6 tt {
- font-size: inherit;
- }
- .highlight { margin-bottom: 16px; }
- .pl-c { color: #969896; }
- .pl-c1,.pl-s .pl-v { color: #0086b3; }
- .pl-e,.pl-en { color: #795da3; }
- .pl-ent { color: #63a35c; }
- .pl-id { color: #b52a1d; }
- .pl-ii { background-color: #b52a1d;color: #f8f8f8; }
- .pl-k { color: #a71d5d; }
- .pl-mb { color: #333;font-weight: bold; }
- .pl-md { background-color: #ffecec;color: #bd2c00; }
- .pl-mdr { color: #795da3;font-weight: bold; }
- .pl-mh,.pl-mh .pl-en,.pl-ms { color: #1d3e81;font-weight: bold; }
- .pl-mi { color: #333;font-style: italic; }
- .pl-mi1 { background-color: #eaffea;color: #55a532; }
- .pl-ml { color: #693a17; }
- .pl-mo { color: #1d3e81; }
- .pl-mq { color: #008080; }
- .pl-s,.pl-pds,.pl-s .pl-pse .pl-s1,.pl-sr,.pl-sr .pl-cce,.pl-sr .pl-sre,.pl-sr .pl-sra { color: #183691; }
- .pl-smi,.pl-s .pl-s1 { color: #333; }
- .pl-sr .pl-cce { color: #63a35c;font-weight: bold; }
- .pl-v { color: #ed6a43; }
- #footer {
- color: #777;
- font-size: 11px;
- margin: 10px auto;
- text-align: right;
- white-space: nowrap;
- width: 978px;
- }
- </style>
- </head>
- <body>
- <p><a target="_blank" rel="noopener noreferrer" href="../../src/hi/static/img/hi-logo-w-tagline-197x96.png"><img src="../../src/hi/static/img/hi-logo-w-tagline-197x96.png" alt="Home Information Logo" width="128" style="max-width: 100%;"></a></p>
-<div class="markdown-heading"><h1 class="heading-element">Development Workflow</h1><a id="user-content-development-workflow" class="anchor" aria-label="Permalink: Development Workflow" href="#development-workflow"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
-<ul>
-<li>See the <a href="../../CONTRIBUTING.md">Contributing Page</a> for general information about contributing.</li>
-<li>See the <a href="Setup.md">Development Page</a> for how to set up your development environment.</li>
-</ul>
-<div class="markdown-heading"><h2 class="heading-element">Branching Strategy</h2><a id="user-content-branching-strategy" class="anchor" aria-label="Permalink: Branching Strategy" href="#branching-strategy"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
-<ul>
-<li>
-<strong>Main Branch</strong> (<code>master</code>): Stable, production-ready code. Only updated by the prohect maintainers.</li>
-<li>
-<strong>Development Branch</strong> (<code>staging</code>): Active development happens here. Pull requests target this branch, with maintainers controlling merges.</li>
-<li>
-<strong>Feature Branches</strong>: Contributors will fork the repo and branch off <code>staging</code> branch for their work. Anyone can fork the repository, create a feature branch and submit PRs against the <code>staging</code> branch.</li>
-</ul>
-<div class="markdown-heading"><h2 class="heading-element">Making Changes - Overview</h2><a id="user-content-making-changes---overview" class="anchor" aria-label="Permalink: Making Changes - Overview" href="#making-changes---overview"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
-<ul>
-<li>Always work off the latest <code>staging</code> branch to avoid merge conflicts.</li>
-<li>Create an issue and a branch (issues highly encouraged for most PRs).</li>
-<li>Do your thing and add to and/or change the code: use clear commit messages.</li>
-<li>Create a PR: should be focused on a single feature or fix.</li>
-</ul>
-<div class="markdown-heading"><h2 class="heading-element">Ensure Your Code is in Sync</h2><a id="user-content-ensure-your-code-is-in-sync" class="anchor" aria-label="Permalink: Ensure Your Code is in Sync" href="#ensure-your-code-is-in-sync"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
-<p>Switch to your local copy of staging branch:</p>
-<div class="highlight highlight-source-shell"><pre>git checkout staging</pre></div>
-<p>Fetch the latest changes from upstream:</p>
-<div class="highlight highlight-source-shell"><pre>git fetch upstream</pre></div>
-<p>Merge upstream changes into your fork's dev branch:</p>
-<div class="highlight highlight-source-shell"><pre>git merge upstream/staging</pre></div>
-<p>Push the updated dev branch to your fork:</p>
-<div class="highlight highlight-source-shell"><pre>git push origin staging</pre></div>
-<div class="markdown-heading"><h2 class="heading-element">Create an Issue and Branch</h2><a id="user-content-create-an-issue-and-branch" class="anchor" aria-label="Permalink: Create an Issue and Branch" href="#create-an-issue-and-branch"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
-<p>All PRs are encouraged to be associated with an issue and the branch should use the issue number in its name. For minor fixes, or test-only changes, skipping an issue is OK, but anything more substantial should have an issue for discussions and reference.</p>
-<p>Issues (and hence branches) come in a few flavors with associated conventions. In generalm a branch will have both the issue number and a user-chosen, short mnemonic to be slightly more descriptive. Here are the conventions:</p>
-<table>
-<thead>
-<tr>
-<th>Type</th>
-<th>Issue?</th>
-<th>Branch</th>
-<th>Notes</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td>feature</td>
-<td>YES</td>
-<td>feature/$(ISSUE_NUM}-${MNEMONIC}</td>
-<td>New Development</td>
-</tr>
-<tr>
-<td>bugfix</td>
-<td>YES</td>
-<td>bugfix/$(ISSUE_NUM}-${MNEMONIC}</td>
-<td>Bug Fixes</td>
-</tr>
-<tr>
-<td>docs</td>
-<td>YES</td>
-<td>docs/$(ISSUE_NUM}-${MNEMONIC}</td>
-<td>Documentation</td>
-</tr>
-<tr>
-<td>ops</td>
-<td>YES</td>
-<td>ops/$(ISSUE_NUM}-${MNEMONIC}</td>
-<td>Non-app, deployment, etc.</td>
-</tr>
-<tr>
-<td>tests</td>
-<td>NO</td>
-<td>tests/${MNEMONIC}</td>
-<td>For test-only changes</td>
-</tr>
-<tr>
-<td>refactor</td>
-<td>YES</td>
-<td>refactor/$(ISSUE_NUM}-${MNEMONIC}</td>
-<td>Only if no new behaviors</td>
-</tr>
-<tr>
-<td>tweak</td>
-<td>NO</td>
-<td>tweak/${MNEMONIC}</td>
-<td>For small, obvious PRs</td>
-</tr>
-</tbody>
-</table>
-<p>If you are contributing something new, without an existing issue, please create an issue first using the appropriate template: feature, bugfix, etc.. It is generally always better to think about what you are about to do before doing it. Creating an issue is a forcing function for thinking through and communicating your plans.</p>
-<p>Once your code is up-to-date, an issue number exists and a mnemonic chosen, you can create your local branch off the current staging branch:</p>
-<div class="highlight highlight-source-shell"><pre>git checkout -b feature/<span class="pl-s"><span class="pl-pds">$(</span>ISSUE_NUM}-<span class="pl-smi">${MNEMONIC}</span> upstream/staging</span></pre></div>
-<div class="markdown-heading"><h2 class="heading-element">Do Your Thing</h2><a id="user-content-do-your-thing" class="anchor" aria-label="Permalink: Do Your Thing" href="#do-your-thing"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
-<ul>
-<li>Make your changes to the code.</li>
-<li>Test your changes locally (and add unit tests).</li>
-<li>Stage changes: <code>git add .</code>
-</li>
-<li>Commit changes: <code>git commit -m "Add feature: [brief description]"</code>
-</li>
-<li>Push branch to your fork: <code>git push origin feature/$(ISSUE_NUM}-${MNEMONIC}</code>
-</li>
-</ul>
-<div class="markdown-heading"><h2 class="heading-element">Submit a Pull Request (PR)</h2><a id="user-content-submit-a-pull-request-pr" class="anchor" aria-label="Permalink: Submit a Pull Request (PR)" href="#submit-a-pull-request-pr"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
-<ul>
-<li>Go to your fork on GitHub: <a href="https://github.com/$%7BYOURUSERNAME%7D/home-information">https://github.com/${YOURUSERNAME}/home-information</a>
-</li>
-<li>Click the "Compare &amp; pull request" button that appears after your push.</li>
-<li>Ensure the base repository is set to <code>cassandra/home-information -&gt; staging</code>
-</li>
-<li>Ensure the compare branch is set to: <code>${YOURUSERNAME}/home-information -&gt; feature/${YOUR_FEATURE_NAME}</code>
-</li>
-<li>Fill out the PR template (describe what your change does).</li>
-<li>Submit the PR and wait for review!</li>
-</ul>
-<div class="markdown-heading"><h2 class="heading-element">PR Reviews</h2><a id="user-content-pr-reviews" class="anchor" aria-label="Permalink: PR Reviews" href="#pr-reviews"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
-<p>During PR review, a decision will be made on whether to squash or rebase:</p>
-<ul>
-<li>
-<strong>Squash and Merge (default)</strong>: For most PRs</li>
-<li>
-<strong>Rebase and Merge</strong>: for well-structured PRs that need commit history</li>
-</ul>
-<div class="markdown-heading"><h2 class="heading-element">Post-PR Cleanup</h2><a id="user-content-post-pr-cleanup" class="anchor" aria-label="Permalink: Post-PR Cleanup" href="#post-pr-cleanup"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
-<ul>
-<li>After merging, you should consider deleting the branch to keep your forked repository clean.</li>
-<li>Get your local and forked <code>staging</code> branch up to date with the upstream changes (see above).</li>
-</ul>
-
- </body>
-</html>