Merge pull request #18 from hass-agent/beta

Merge beta into main

.github/ISSUE_TEMPLATE/bug-problem-report.md → .github/ISSUE_TEMPLATE/bug-report.md

@@ -1,26 +1,24 @@
 ---
-name: Bug/problem report
-about: Create a bug/issue report for any problems
+name: Bug Report
+about: Create a bug report for any problems while using the documentation
 title: ""
 labels: ""
 assignees: ""
 ---
 
 Make sure this issue isn't already listed here before submitting.
 
-If you need help with Direct URL's checkout this guide:
-
-https://hass-agent-beta.github.io/contributing/reporting-issues/
+Before creating an issue checkout our guide here: https://hass-agent.github.io/latest/contributing/reporting-issues/
 
 ---
 
 ## Describe the bug/problem
 
-A clear and concise description of what the bug or problem with a section is.
+A clear and concise description of what the bug or problem is.
 
 ## Where does this issue occur?
 
-**Include Direct URL to section; Info above**
+**Include Permalink to the section if applicable. Info in the guide above**
 
 ## Expected behaviour / expected information
 

.github/ISSUE_TEMPLATE/feature-request.md

@@ -0,0 +1,33 @@
+---
+name: Feature Request
+about: Suggest a new feature or improvement
+title: ""
+labels: ""
+assignees: ""
+---
+
+Before creating a feature request, please check if a similar request already exists.
+
+Before submitting, refer to our guide on reporting issues/improvements here: https://hass-agent.github.io/latest/contributing/reporting-issues/
+
+---
+
+## Feature Description
+
+A clear and concise description of the feature you are proposing.
+
+## Use Case
+
+Explain the scenario or use case where this feature would be beneficial. Include a permalink to the docs if applicable(More info in the guide above).
+
+## Expected Behavior
+
+Describe the expected behavior or outcome after the implementation of the proposed feature.
+
+## Additional Context
+
+Provide any additional context or information that might be relevant to the feature request.
+
+## Optional: Design or Mockups
+
+If you have any designs, mockups, or visual concepts related to the feature, you can attach them here.

.github/workflows/release-beta.yml

@@ -45,10 +45,7 @@ jobs:
       - name: Deploy copy of beta with incremented version number for development
         run: |
           mike deploy -p -u ${{ inputs.new_version }} beta -t beta
-      - name: Merge beta branch with main
-        run: |
-          git fetch --unshallow
-          git checkout main
-          git pull
-          git merge --no-ff beta -m "Auto-Merge beta into main"
-          git push
+      - name: Create Pull Request from beta to main
+        run: gh pr create --base main --head beta --title "Merge beta into main" --body "Auto-Merge beta into main"
+        env:
+          GH_TOKEN: ${{ secrets.PAT_TOKEN }}

Dockerfile

@@ -0,0 +1,11 @@
+FROM squidfunk/mkdocs-material:9.5.0
+
+WORKDIR /app
+
+COPY . /app
+RUN pip install -r requirements.txt
+
+
+EXPOSE 8000
+
+CMD ["serve", "--dev-addr=0.0.0.0:8000"]

README.md

@@ -1,12 +1,12 @@
 <p align="center">
-  <a href="https://github.com/LAB02-Research/HASS.Agent">
-    <img src="https://raw.githubusercontent.com/LAB02-Research/HASS.Agent/08310c474780107f63053cf02ce52f80e49408cb/images/logo_256.png"  alt="HASS.Agent" class="logo" />
+  <a href="https://github.com/hass-agent/HASS.Agent">
+    <img src="docs/assets/images/logo/logo-256.png"  alt="HASS.Agent" />
   </a>
 </p>
 <p align="center">
   <strong>
     View the documentation 
-    <a href="https://hass-agent-beta.github.io/">here</a>
+    <a href="https://hass-agent.io/">here</a>
   </strong>
 </p>
 <br clear="left" />
@@ -15,27 +15,22 @@
 
 ## Overview
 
-This repository contains all the files used to create [HASS.Agent's documentation](https://hass-agent-beta.github.io/).
+This repository contains all the files used to create [HASS.Agent's documentation](https://hass-agent.io/).
 
 ### Branches
 
-- `main` --> contains the source code
+- `main` --> contains the current "latest" docs version
+- `beta` --> contains the current "beta" docs version
 - `gh-pages` --> deployable (builded) version
 
 ## Deployed Documentation
 
-The documentation is deployed here on github pages, you can view it [here](https://hass-agent-beta.github.io/).
+The documentation is deployed here on github pages, you can view it [here](https://hass-agent.io/).
 
 ## Development / Contributing
 
-> Pleas do **not** submit pull requests to this repo.
-
-If you would like to help out with development or translating of the HASS.Agent application check out our guide [here](https://hass-agent-beta.github.io/contributing/).
+If you would like to help out with development or translating of the HASS.Agent application check out our guide [here](https://hass-agent.io/latest/contributing/).
 
 ### Contributing to the documentation
 
-You can either submit github tickets with the info you want added to the documentation or make the changes yourself. You can submit a ticket for any issues, edits or info you want added to the docs. If you want to make the changes yourself continue reading.
-
-### Editing the docs yourself
-
-Checkout [this](https://hass-agent-beta.github.io/contributing/#helping-out-with-the-documentation) page for information on contributing to the documentation.
+You can either submit github tickets with the info you want added to the documentation or make the changes yourself. You can submit a ticket for any issues, edits or info you want added to the docs. If you want to make the changes yourself checkout [the docs](https://hass-agent.io/latest/contributing/#helping-out-with-the-documentation).

docker-compose.yml

@@ -0,0 +1,9 @@
+version: "3"
+services:
+  docs:
+    build: .
+    container_name: hass-agent-docs
+    ports:
+      - "8000:8000"
+    volumes:
+      - .:/app

docs/stylesheets/extra.css → docs/assets/stylesheets/extra.css

@@ -3,3 +3,7 @@
   --md-primary-fg-color--light: #41bdf5;
   --md-primary-fg-color--dark: #41bdf5;
 }
+
+.md-header__button.md-logo img {
+  height: 2rem;
+}

docs/changelog.md

@@ -0,0 +1,4 @@
+---
+title: Changelog
+template: changelog.html
+---

docs/contributing/developer-resources/current-devs.md

@@ -0,0 +1,31 @@
+# Current Code Maintainers
+
+Here you can find the list of current developers and what they help contribute. You will find discord and github links if you need to contact them for help with development.
+
+!!! warning
+
+    **Do not spam**
+    We have given you these links so you can use them correctly and to get help, they are not for you to message about some small issue that the rest of the community can help with. If you need help with their specific contributions or need to message the lead devs you can use the links in the tabs below.
+
+??? question "Get added to this list"
+
+    If you actively maintain the codebase for a week or more, head over to the Discord server and ask one of the lead devs to verify you and add you to this list.
+
+=== "Client/App"
+
+    **Lead Dev**
+
+    - **[amadeo-alex](https://github.com/amadeo-alex){: target="\_blank"}:** Creator of the unofficial version of HASS.Agent
+        - Discord: [Amadeo](https://discord.com/users/135056992745029632){: target="\_blank"}
+
+    **Other Contributors**
+
+    - **[MinimumDowntime](https://github.com/MinimumDowntime){: target="\_blank"}:** Github Actions Workflows
+        - Discord: [Automaton](https://discord.com/users/350097059640115200){: target="\_blank"}
+
+=== "Documentation"
+
+    **Lead Dev**
+
+    - **[DrR0x-Glitch](https://github.com/drr0x){: target="\_blank"}:** Creator of this documentation
+        - Discord: [DrR0x](https://discord.com/users/638245963240046592){: target="\_blank"}

docs/contributing/developer-resources/index.md

@@ -0,0 +1,7 @@
+# Extra Resources for Developers
+
+This section contains extra and shared resources for developers. You will find information in here that will be used across parts of HASS.Agent.
+
+### Versioning
+
+The HASS.Agent client uses a version system that is shared with the documentation, you can read more on this [here](./version-system.md).

docs/contributing/developer-resources/version-system.md

@@ -0,0 +1,103 @@
+# HASS.Agent's version system
+
+!!! warning
+
+    You must read and understand this entire page if you want to be able to develop any part of HASS.Agent. It helps you to understand the versioning and how to understand different versions of HASS.Agent
+
+## Overview
+
+#### HASS.Agent is based on one version system
+
+All parts off HASS.Agent use semver to keep track of their versions.
+
+## Summary of SemVer
+
+This is a general summary of SemVer and how you will indicate different versions throughout development. You may be tempted to skip this if you know SemVer but don't, because how we indicate dev builds and betas is different to others.
+
+### Stable release versions
+
+All release version numbers of HASS.Agent look like this: `<major>.<minor>.<patch>`  
+An example of a released version number: `1.5.4`
+
+#### Major
+
+The major version number is rarely changed, if you are reading this documentation you will most likely never have to change this. But for your information it is only changed when breaking API updates are added. So version `2.*.*` client, is **not** backwards compatible with version `2.*.*`. This also means that all versions of `1.*.*` will be backwards compatible, there may be small warnings or missing features but all previous API calls and features work as intended. Basically this version number only needs to be incremented when no backwards compatability is added. This also forces the dev team to not release backwards compatible updates very often.
+
+???+ example
+
+    - Version `1.4.2` of the client **does** have backwards compatibility with version `1.8.3`
+    - Version `2.3.2` of the lient **does not** have backwards compatibility with version `1.8.3`
+
+#### Minor
+
+The minor version number is to be incremented whenever new features are added in a backwards compatible way. More than one feature **can** be added per version number, however they all have to have backwards compatibility.
+
+???+ example
+
+    - Version `1.4.1` of the client will have **less** features than `1.5.0`
+    - Version `1.6.0` of the client will have **more** features than `1.5.0`
+
+    **Note that in both of these examples the versions are backwards compatible.**
+
+#### Patch
+
+The patch version number is to be incremented whenever bug fixes(patches) are released in a backwards compatible way. All bug fixes are to be released in a backwards compatible way anyway, so basically everytime a patch is released, this number will be incremented. The important thing to note about the patch version number is that **no new features** can be added.
+
+???+ example
+
+    - Version `1.3.0` of the client will have more bugs than `1.3.1` of the client
+    - Version `1.5.6` of the client will have more patches and therefore less bugs, than `1.5.2` of the client
+
+    **No new features are added between the versions in these examples. Only bug fixes and patches are added.**
+
+### Beta developmental versions
+
+During the development of a new version of the HASS.Agent client beta versions of the code will exist. These versions will be denoted like this: `<major>.<minor>.<patch>-beta.<beta-version>` You will notice the only difference is the addition of the `-beta` flag and the fourth version number `<beta-version>`
+The first beta version of the example upcoming `1.5.3` release would look like this: `1.5.3-beta.0`
+
+#### Beta version
+
+The beta version number is to be incremented whenever a new beta version of the code is built or released for testing.
+
+???+ example annotate
+
+    > The current stable version is `2.5.4` and the dev team is working on a new feature
+
+    The beta version during the first development update should be `2.6.0-beta.0`
+
+    Everytime a new development update is added to this feature the last number should be incremented.
+
+    > The dev team has now finished working on this feature
+
+    The stable version for release should be `2.6.0`
+
+    > The dev team has found bugs and is working on a hotfix. They are in devlopment of the second hotfix right now.
+
+    The current beta version should be `2.6.1-beta.1` (1)
+
+    > They have now completed this hotfix
+
+    The stable release version should be `2.6.1`
+
+1.  We use 1 for the `<beta-version>` here, because hotfix 1 was .0 and hotfix 2 was .1
+
+### Other info
+
+#### Resetting numbers
+
+Whenever a "parent" version number is incremented the "children" numbers must be rest to zero.
+
+???+ example
+
+    - If the current version is `1.5.6` and a new backwards **compatible** feature is being added the new version will be `1.6.0`
+    - If the current version is `1.5.6` and a new backwards **incompatible** feature is being added the new version will be `2.0.0`
+
+#### Documentation
+
+The documentation operates on version of just `<major>.<minor>` This will still match the client because no major documentation change will happen during a patch of the HASS.Agent client.
+
+The other difference between this version system and the client's version system is that beta version attributes will not exist. In the documentation if the upcoming release is going to be `1.5.0` and the current beta version is `1.5.0-beta.3` then the docs will have `1.5` with the label/attribute `beta`.
+
+## Relationship between the client and the integration
+
+Both the client and the integration are going to be using SemVer, however it will **not** be the same version. Instead when you checkout the installation for HASS.Agent it will tell you what version of the integration is required. The other thing is that most of the integration's development will be backwards compatible and not move up from version `2`.

docs/contributing/hass-agent-documentation/adding-pages.md

@@ -0,0 +1,35 @@
+# Adding new pages
+
+You can add new pages anywhere in the documentation if you feel the need to. However we do recommend checking in with the other docs developers before adding a new page, to make sure it is needed.
+
+## Creating the page
+
+You start by creating a new .md with an all lowercase name, you can use `-` dashes in place of spaces. For example this file is called `adding-pages.md` This file should be located in the section you want it, for example; if you want a new page in this documentation contributing section you will create the page in the `docs/contributing/hass-agent-documentation/`.
+
+Now you can use a heading 1 to indicate the name of this page. Example: `# Adding new pages`
+
+## Adding it to the navtree
+
+You now need to open the `mkdocs.yml` file in the root of the documentation. At the very bottom you will see:
+
+```yaml
+nav:
+  - Home: index.md
+```
+
+To add your page you need to find the section you have placed your file in, for example a file placed in the `docs/contributing/hass-agent-documentation` should be added under the:
+
+```yaml
+nav:
+  - Helping Out:
+      - Developing the Documentation:
+```
+
+You create a new entry by indenting and adding a `- ` and then writing the name of your page that you want in the sidebar navigation, so keep it short. Then you add a `:` and follow it by the directory of the file.
+???+ note
+
+    This directory starts in the docs folder so you will just write `contributing/hass-agent-documentation`, not `docs/contributing/hass-agent-documentation`.
+
+## Editing and Testing the page
+
+You can now edit the page and fill it with content, all of the changes should show in your browser and the page should be visible in the left navigation sidebar.