Skip to content

Commit

Permalink
Merge pull request #18 from hass-agent/beta
Browse files Browse the repository at this point in the history
Merge beta into main
  • Loading branch information
DrR0X-glitch authored Jan 11, 2024
2 parents efe9a31 + 31509a1 commit 9c91f6c
Show file tree
Hide file tree
Showing 58 changed files with 2,196 additions and 1,211 deletions.
Original file line number Diff line number Diff line change
@@ -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

Expand Down
33 changes: 33 additions & 0 deletions .github/ISSUE_TEMPLATE/feature-request.md
Original file line number Diff line number Diff line change
@@ -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.
11 changes: 4 additions & 7 deletions .github/workflows/release-beta.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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 }}
11 changes: 11 additions & 0 deletions Dockerfile
Original file line number Diff line number Diff line change
@@ -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"]
695 changes: 21 additions & 674 deletions LICENSE

Large diffs are not rendered by default.

23 changes: 9 additions & 14 deletions README.md
Original file line number Diff line number Diff line change
@@ -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" />
Expand All @@ -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).
9 changes: 9 additions & 0 deletions docker-compose.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
version: "3"
services:
docs:
build: .
container_name: hass-agent-docs
ports:
- "8000:8000"
volumes:
- .:/app
Binary file modified docs/assets/images/logo/logo-128.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/assets/images/logo/logo-256.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed docs/assets/images/logo/logo_256.png
Binary file not shown.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/assets/images/screenshots/sensor-new.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/assets/images/screenshots/text-to-speech.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Original file line number Diff line number Diff line change
Expand Up @@ -3,3 +3,7 @@
--md-primary-fg-color--light: #41bdf5;
--md-primary-fg-color--dark: #41bdf5;
}

.md-header__button.md-logo img {
height: 2rem;
}
4 changes: 4 additions & 0 deletions docs/changelog.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
---
title: Changelog
template: changelog.html
---
31 changes: 31 additions & 0 deletions docs/contributing/developer-resources/current-devs.md
Original file line number Diff line number Diff line change
@@ -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"}
7 changes: 7 additions & 0 deletions docs/contributing/developer-resources/index.md
Original file line number Diff line number Diff line change
@@ -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).
103 changes: 103 additions & 0 deletions docs/contributing/developer-resources/version-system.md
Original file line number Diff line number Diff line change
@@ -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`.
35 changes: 35 additions & 0 deletions docs/contributing/hass-agent-documentation/adding-pages.md
Original file line number Diff line number Diff line change
@@ -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.
Loading

0 comments on commit 9c91f6c

Please sign in to comment.