Merge branch 'current' into next
This commit is contained in:
Fabian Affolter
commit
2f8bd0b77e
38 changed files with 199 additions and 181 deletions
|
|
@ -15,12 +15,14 @@ ha_release: 0.57
|
|||
|
||||
First time users may find it helpful to switch between multilanguage and single language view using the <img src='/images/frontend/lokalise-multilanguage-view-button.png' alt="Multilanguage view" style="width: 17px; border: none;"/> button. For more information about the translation workflow, please see the [Lokalise translation workflow documents](https://docs.lokalise.co/category/iOzEuQPS53-for-team-leads-and-translators).
|
||||
|
||||
Some translation strings will contain special placeholders that will be replaced later. Placeholders shown in square brackets `[]` are [Lokalise key references](https://docs.lokalise.co/article/KO5SZWLLsy-key-referencing). These are primarily used to link translation strings that will be duplicated. Different languages may not have the same duplicates as English, and are welcome to link duplicate translations that are not linked in English. Placeholders shown in curly brackets `{}` are [translation arguments](https://formatjs.io/guides/message-syntax/) that will be replaced with a live value when Home Assistant is running. Any translation argument placeholders present in the original string must be included in the translated string. These may include special syntax for defining plurals or other replacement rules. The linked format.js guide explains the syntax for adding plural definitions and other rules.
|
||||
|
||||
<p class='note'>
|
||||
The translation of the Home Assistant frontend is still a work in progress. More phrases will be available for translation soon.
|
||||
</p>
|
||||
|
||||
## {% linkable_title Translation placeholders %}
|
||||
|
||||
Some translation strings will contain special placeholders that will be replaced later. Placeholders shown in square brackets `[]` are [Lokalise key references](https://docs.lokalise.co/article/KO5SZWLLsy-key-referencing). These are primarily used to link translation strings that will be duplicated. Different languages may not have the same duplicates as English, and are welcome to link duplicate translations that are not linked in English. Placeholders shown in curly brackets `{}` are [translation arguments](https://formatjs.io/guides/message-syntax/) that will be replaced with a live value when Home Assistant is running. Any translation argument placeholders present in the original string must be included in the translated string. These may include special syntax for defining plurals or other replacement rules. The linked format.js guide explains the syntax for adding plural definitions and other rules.
|
||||
|
||||
## {% linkable_title Rules %}
|
||||
1. Only native speakers should submit translations.
|
||||
2. Stick to [Material Design guidelines](https://material.io/guidelines/style/writing.html).
|
||||
|
|
|
|||
|
|
@ -9,22 +9,22 @@ sharing: true
|
|||
footer: true
|
||||
---
|
||||
|
||||
This page describes the steps for publishing a new Home Assistant release. Those steps requires that you don't use forks but work with the repositories themself. The [hass-release](https://github.com/home-assistant/hass-release) script is a helper to do a release.
|
||||
This page describes the steps for publishing a new Home Assistant release. Those steps requires that you don't use forks but work with the repositories themself. The [hass-release](https://github.com/home-assistant/hass-release) script is a helper to do a release.
|
||||
|
||||
### {% linkable_title Release preparation (3 days before release) %}
|
||||
|
||||
### {% linkable_title GitHub %}
|
||||
|
||||
1. Merge `master` into `dev` to make the PR mergeable.
|
||||
2. Cut a release branch from `dev`. Example name `release-0-57`.
|
||||
3. Create a pull request from the release branch to `master` with the upcoming release number as the title.
|
||||
4. Update `homeassistant/const.py` with the correct version number (remove the `dev` tag) and push that commit to release branch.
|
||||
1. Cut a release branch from `dev`. Example name `release-0-57`.
|
||||
1. Create a pull request from the release branch to `master` with the upcoming release number as the title.
|
||||
1. Update `homeassistant/const.py` with the correct version number (remove the `dev` tag) and push that commit to release branch.
|
||||
|
||||
### {% linkable_title Website %}
|
||||
|
||||
1. Merge `current` into `next`
|
||||
2. Cut release branch of `next`. For example `release-0-57`.
|
||||
3. Open a PR from release branch to `current` with the upcoming release number as the title.
|
||||
1. Cut release branch of `next`. For example `release-0-57`.
|
||||
1. Open a PR from release branch to `current` with the upcoming release number as the title.
|
||||
|
||||
## {% linkable_title Release day %}
|
||||
|
||||
|
|
@ -33,22 +33,22 @@ From creating the release branch till it has been merged, we tag bugfixes with t
|
|||
### {% linkable_title GitHub %}
|
||||
|
||||
1. Cherry-pick the milestoned PRs that need to get into the release `python3 -m hassrelease milestone_cherry_pick 0.57`
|
||||
2. Run `python3 -m hassrelease release_notes 0.56` for the release notes.
|
||||
3. Once the release notes has been generated, issue `python3 -m hassrelease milestone_close 0.56`
|
||||
4. Merge pull request (DO NOT SQUASH!). Use `Merge pull request`.
|
||||
5. Go to [releases](https://github.com/home-assistant/home-assistant/releases), click `Draft a new release` and tag a new release on the `master` branch. "Tag version" and "Release title" are the version number (`O.x` for major version, `0.x.y` for minor and bug fix releases). Release description is the text from PR. Press "Publish release" to finish the process.
|
||||
6. Merge `master` into `dev`.
|
||||
7. Update `homeassistant/const.py` with the upcoming version number (including the `dev` tag) and push that commit to the `dev` branch.
|
||||
1. Run `python3 -m hassrelease release_notes 0.56` for the release notes.
|
||||
1. Once the release notes has been generated, issue `python3 -m hassrelease milestone_close 0.56`
|
||||
1. Merge pull request (DO NOT SQUASH!). Use `Merge pull request`.
|
||||
1. Go to [releases](https://github.com/home-assistant/home-assistant/releases), click `Draft a new release` and tag a new release on the `master` branch. "Tag version" and "Release title" are the version number (`O.x` for major version, `0.x.y` for minor and bug fix releases). Release description is the text from PR. Press "Publish release" to finish the process.
|
||||
1. Merge `master` into `dev`.
|
||||
1. Update `homeassistant/const.py` with the upcoming version number (including the `dev` tag) and push that commit to the `dev` branch.
|
||||
|
||||
### {% linkable_title Website %}
|
||||
|
||||
1. Create a blog post in the release branch and base it on the text of the PR in the main repository. Add images, additional text, links, etc. if it adds value. Tag each platform/component in a message to documentation.
|
||||
2. Create missing documentation as stubs.
|
||||
3. Run `credits_generator`.
|
||||
4. Update `_config.yml` with a link to the new release blog post and version number (at the bottom of the file).
|
||||
5. Merge `current` into release branch (`$ git checkout release-0-40 && git merge current`) to make the PR mergeable.
|
||||
6. Merge pull request (blog post, updated frontpage, and all new documentation) to `current`. DO NOT SQUASH!
|
||||
7. Merge `current` into `next`.
|
||||
1. Create missing documentation as stubs.
|
||||
1. Run `credits_generator`.
|
||||
1. Update `_config.yml` with a link to the new release blog post and version number (at the bottom of the file).
|
||||
1. Merge `current` into release branch (`$ git checkout release-0-40 && git merge current`) to make the PR mergeable.
|
||||
1. Merge pull request (blog post, updated frontpage, and all new documentation) to `current`. DO NOT SQUASH!
|
||||
1. Merge `current` into `next`.
|
||||
|
||||
### {% linkable_title Docker Hub %}
|
||||
|
||||
|
|
@ -65,10 +65,10 @@ Checkout the `master` branch and run `script/release` to publish the new release
|
|||
## {% linkable_title Bugfix Release %}
|
||||
|
||||
1. Checkout `master` and update it. `git checkout master && git pull --rebase`
|
||||
2. Create a new release branch from `master`. `git checkout -b release-0-56-2`
|
||||
3. Cherry-pick the PRs which were milestoned.
|
||||
4. Update `homeassistant/const.py` with the correct version number (increment `PATCH_VERSION`) and push that commit to release branch.
|
||||
5. Create a pull request from the release branch to `master` with the upcoming release number as the title.
|
||||
6. Merge pull request (DO NOT SQUASH!). Use `Merge pull request`.
|
||||
7. Go to [releases](https://github.com/home-assistant/home-assistant/releases), click `Draft a new release` and tag a new release on the `master` branch. "Tag version" and "Release title" are the version number (`O.x` for major version, `0.x.y` for minor and bug fix releases). Release description is the text from PR. Press "Publish release" to finish the process.
|
||||
8. [Publish](/developers/releasing/#python-package-index) the new release on PyPI.
|
||||
1. Create a new release branch from `master`. `git checkout -b release-0-56-2`
|
||||
1. Cherry-pick the PRs which were milestoned.
|
||||
1. Update `homeassistant/const.py` with the correct version number (increment `PATCH_VERSION`) and push that commit to release branch.
|
||||
1. Create a pull request from the release branch to `master` with the upcoming release number as the title.
|
||||
1. Merge pull request (DO NOT SQUASH!). Use `Merge pull request`.
|
||||
1. Go to [releases](https://github.com/home-assistant/home-assistant/releases), click `Draft a new release` and tag a new release on the `master` branch. "Tag version" and "Release title" are the version number (`O.x` for major version, `0.x.y` for minor and bug fix releases). Release description is the text from PR. Press "Publish release" to finish the process.
|
||||
1. [Publish](/developers/releasing/#python-package-index) the new release on PyPI.
|
||||
|
|
|
|||
|
|
@ -11,8 +11,8 @@ footer: true
|
|||
|
||||
Home Assistant runs a web server accessible on port 8123.
|
||||
|
||||
* http://IP_ADDRESS:8123/ is an interface to control Home Assistant.
|
||||
* http://IP_ADDRESS:8123/api/ is a Rest API.
|
||||
* http://IP_ADDRESS:8123/ is an interface to control Home Assistant.
|
||||
* http://IP_ADDRESS:8123/api/ is a Rest API.
|
||||
|
||||
The API accepts and returns only JSON encoded objects. All API calls have to be accompanied by the header `X-HA-Access: YOUR_PASSWORD` (YOUR_PASSWORD as specified in your `configuration.yaml` file in the [`http:` section](/components/http/)).
|
||||
|
||||
|
|
@ -27,7 +27,7 @@ curl -X GET \
|
|||
http://IP_ADDRESS:8123/ENDPOINT
|
||||
```
|
||||
|
||||
Another option is to use Python and the [Requests](http://docs.python-requests.org/en/latest/) module.
|
||||
Another option is to use Python and the [Requests](http://docs.python-requests.org/en/latest/) module. =
|
||||
|
||||
```python
|
||||
from requests import get
|
||||
|
|
@ -46,16 +46,17 @@ You can append `?api_password=YOUR_PASSWORD` to any URL to log in automatically.
|
|||
|
||||
Successful calls will return status code 200 or 201. Other status codes that can return are:
|
||||
|
||||
- 400 (Bad Request)
|
||||
- 401 (Unauthorized)
|
||||
- 404 (Not Found)
|
||||
- 405 (Method not allowed)
|
||||
- 400 (Bad Request)
|
||||
- 401 (Unauthorized)
|
||||
- 404 (Not Found)
|
||||
- 405 (Method not allowed)
|
||||
|
||||
### {% linkable_title Actions %}
|
||||
|
||||
The API supports the following actions:
|
||||
|
||||
#### {% linkable_title GET /api/ %}
|
||||
|
||||
Returns a message if the API is up and running.
|
||||
|
||||
```json
|
||||
|
|
@ -72,11 +73,12 @@ $ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
|
|||
```
|
||||
|
||||
#### {% linkable_title GET /api/config %}
|
||||
|
||||
Returns the current configuration as JSON.
|
||||
|
||||
```json
|
||||
{
|
||||
"components":[
|
||||
{
|
||||
"components":[
|
||||
"sensor.cpuspeed",
|
||||
"frontend",
|
||||
"config.core",
|
||||
|
|
@ -108,7 +110,7 @@ Returns the current configuration as JSON.
|
|||
"volume":"L"
|
||||
},
|
||||
"version":"0.56.2",
|
||||
"whitelist_external_dirs":[
|
||||
"whitelist_external_dirs":[
|
||||
"/home/ha/.homeassistant/www",
|
||||
"/home/ha/.homeassistant/"
|
||||
]
|
||||
|
|
@ -123,6 +125,7 @@ $ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
|
|||
```
|
||||
|
||||
#### {% linkable_title GET /api/discovery_info %}
|
||||
|
||||
Returns basic information about the Home Assistant instance as JSON.
|
||||
|
||||
```json
|
||||
|
|
@ -142,6 +145,7 @@ $ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
|
|||
```
|
||||
|
||||
#### {% linkable_title GET /api/events %}
|
||||
|
||||
Returns an array of event objects. Each event object contains event name and listener count.
|
||||
|
||||
```json
|
||||
|
|
@ -165,6 +169,7 @@ $ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
|
|||
```
|
||||
|
||||
#### {% linkable_title GET /api/services %}
|
||||
|
||||
Returns an array of service objects. Each object contains the domain and which services it contains.
|
||||
|
||||
```json
|
||||
|
|
@ -193,13 +198,15 @@ $ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
|
|||
```
|
||||
|
||||
#### {% linkable_title GET /api/history/period/<timestamp> %}
|
||||
|
||||
Returns an array of state changes in the past. Each object contains further details for the entities.
|
||||
|
||||
The `<timestamp>` (`YYYY-MM-DDThh:mm:ssTZD`) is optional and defaults to 1 day before the time of the request. It determines the beginning of the period.
|
||||
|
||||
You can pass the following optional GET parameters:
|
||||
- `filter_entity_id=<entity_id>` to filter on a single entity
|
||||
- `end_time=<timestamp>` to choose the end of the period in URL encoded format (defaults to 1 day).
|
||||
|
||||
- `filter_entity_id=<entity_id>` to filter on a single entity
|
||||
- `end_time=<timestamp>` to choose the end of the period in URL encoded format (defaults to 1 day).
|
||||
|
||||
```json
|
||||
[
|
||||
|
|
@ -249,6 +256,7 @@ $ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
|
|||
```
|
||||
|
||||
#### {% linkable_title GET /api/states %}
|
||||
|
||||
Returns an array of state objects. Each state has the following attributes: entity_id, state, last_changed and attributes.
|
||||
|
||||
```json
|
||||
|
|
@ -276,6 +284,7 @@ $ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
|
|||
```
|
||||
|
||||
#### {% linkable_title GET /api/states/<entity_id> %}
|
||||
|
||||
Returns a state object for specified entity_id. Returns 404 if not found.
|
||||
|
||||
```json
|
||||
|
|
@ -303,6 +312,7 @@ $ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
|
|||
```
|
||||
|
||||
#### {% linkable_title GET /api/error_log %}
|
||||
|
||||
Retrieve all errors logged during the current session of Home Assistant as a plaintext response.
|
||||
|
||||
```text
|
||||
|
|
@ -320,6 +330,7 @@ $ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
|
|||
```
|
||||
|
||||
#### {% linkable_title GET /api/camera_proxy/camera.<entity_id> %}
|
||||
|
||||
Returns the data (image) from the specified camera entity_id.
|
||||
|
||||
Sample `curl` command:
|
||||
|
|
@ -331,6 +342,7 @@ $ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
|
|||
```
|
||||
|
||||
#### {% linkable_title POST /api/states/<entity_id> %}
|
||||
|
||||
Updates or creates the current state of an entity.
|
||||
|
||||
Expects a JSON object that has at least a state attribute:
|
||||
|
|
@ -370,6 +382,7 @@ $ curl -X POST -H "x-ha-access: YOUR_PASSWORD" \
|
|||
```
|
||||
|
||||
#### {% linkable_title POST /api/events/<event_type> %}
|
||||
|
||||
Fires an event with event_type
|
||||
|
||||
You can pass an optional JSON object to be used as `event_data`.
|
||||
|
|
@ -389,6 +402,7 @@ Returns a message if successful.
|
|||
```
|
||||
|
||||
#### {% linkable_title POST /api/services/<domain>/<service> %}
|
||||
|
||||
Calls a service within a specific domain. Will return when the service has been executed or after 10 seconds, whichever comes first.
|
||||
|
||||
You can pass an optional JSON object to be used as `service_data`.
|
||||
|
|
@ -444,6 +458,7 @@ The result will include any states that changed while the service was being exec
|
|||
</p>
|
||||
|
||||
#### {% linkable_title POST /api/template %}
|
||||
|
||||
Render a Home Assistant template. [See template docs for more information.](/topics/templating/)
|
||||
|
||||
```json
|
||||
|
|
@ -467,6 +482,7 @@ $ curl -X POST -H "x-ha-access: YOUR_PASSWORD" \
|
|||
```
|
||||
|
||||
#### {% linkable_title POST /api/event_forwarding %}
|
||||
|
||||
Set up event forwarding to another Home Assistant instance.
|
||||
|
||||
Requires a JSON object that represents the API to forward to.
|
||||
|
|
@ -488,6 +504,7 @@ It will return a message if event forwarding was set up successfully.
|
|||
```
|
||||
|
||||
#### {% linkable_title DELETE /api/event_forwarding %}
|
||||
|
||||
Cancel event forwarding to another Home Assistant instance.<br>
|
||||
|
||||
Requires a JSON object that represents the API to cancel forwarding to.
|
||||
|
|
@ -511,4 +528,3 @@ It will return a message if event forwarding was cancelled successfully.
|
|||
<p class='note'>
|
||||
If your client does not support <code>DELETE</code> HTTP requests you can add an optional attribute <code>_METHOD</code> and set its value to <code>DELETE</code>.
|
||||
</p>
|
||||
|
||||
|
|
|
|||
|
|
@ -11,9 +11,9 @@ footer: true
|
|||
|
||||
Home Assistant contains a WebSocket API. This API can be used to stream information from a Home Assistant instance to any client that implements WebSocket. Implementations in different languages:
|
||||
|
||||
- [JavaScript](https://github.com/home-assistant/home-assistant-js-websocket) - powers the frontend
|
||||
- [Python](https://raw.githubusercontent.com/home-assistant/home-assistant-dev-helper/master/ha-websocket-client.py) - CLI client using [`asyncws`](https://async-websockets.readthedocs.io/en/latest/)
|
||||
- [JavaScript/HTML](https://raw.githubusercontent.com/home-assistant/home-assistant-dev-helper/master/ha-websocket.html) - WebSocket connection in your browser
|
||||
- [JavaScript](https://github.com/home-assistant/home-assistant-js-websocket) - powers the frontend
|
||||
- [Python](https://raw.githubusercontent.com/home-assistant/home-assistant-dev-helper/master/ha-websocket-client.py) - CLI client using [`asyncws`](https://async-websockets.readthedocs.io/en/latest/)
|
||||
- [JavaScript/HTML](https://raw.githubusercontent.com/home-assistant/home-assistant-dev-helper/master/ha-websocket.html) - WebSocket connection in your browser
|
||||
|
||||
Connect your websocket implementation to `ws://localhost:8123/api/websocket`.
|
||||
|
||||
|
|
@ -21,19 +21,19 @@ If you are not using the [`frontend`](/components/frontend/) in your setup then
|
|||
|
||||
## {% linkable_title Server states %}
|
||||
|
||||
1. Client connects.
|
||||
2. Authentication phase starts
|
||||
1. Client connects.
|
||||
1. Authentication phase starts.
|
||||
- If no further authentication necessary for the user: go to 3.
|
||||
- Server sends `auth_required` message.
|
||||
- Client sends `auth` message.
|
||||
- If `auth` message correct: go to 3.
|
||||
- Server sends `auth_invalid`. Go to 6.
|
||||
3. Send `auth_ok` message.
|
||||
4. Authentication phase ends.
|
||||
5. Command phase starts.
|
||||
1. Send `auth_ok` message
|
||||
1. Authentication phase ends.
|
||||
1. Command phase starts.
|
||||
1. Client can send commands.
|
||||
2. Server can send results of previous commands.
|
||||
6. Client or server disconnects session.
|
||||
1. Server can send results of previous commands.
|
||||
1. Client or server disconnects session.
|
||||
|
||||
During the command phase, the client attaches a unique identifier to each message. The server will add this identifier to each message so that the client can link each message to it's origin.
|
||||
|
||||
|
|
@ -219,7 +219,6 @@ The server will respond with a result message to indicate that unsubscribing was
|
|||
}
|
||||
```
|
||||
|
||||
|
||||
### {% linkable_title Calling a service %}
|
||||
|
||||
This will call a service in Home Assistant. Right now there is no return value. The client can listen to `state_changed` events if it is interested in changed entities as a result of a service call.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue