Refactor docs/infos (#169)
* Refactor readme and changelog texts. Signed-off-by: Jerome Luckenbach <github@luckenba.ch> * Adress Review comments. Signed-off-by: Jerome Luckenbach <github@luckenba.ch> * Removed outdated gif. Signed-off-by: Jerome Luckenbach <github@luckenba.ch>pull/172/head
Jerome Luckenbach
GitHub
parent
a7e355e47c
commit
dbcbc244b7
107
CONTRIBUTING.md
107
CONTRIBUTING.md
|
|
@ -2,59 +2,74 @@
|
|||
|
||||
In order to join our forces here, you'd need a few things to get started:
|
||||
|
||||
* [Node.js](https://nodejs.org/en/download/) installed
|
||||
* [Visual Studio Code](https://code.visualstudio.com/) installed
|
||||
* [TypeScript](https://www.typescriptlang.org/docs/home.html) knowledge
|
||||
* [Visual Studio Code Extension Authoring](https://code.visualstudio.com/docs/extensions/overview) knowledge
|
||||
- [Node.js](https://nodejs.org/en/download/) installed
|
||||
- [Visual Studio Code](https://code.visualstudio.com/) installed
|
||||
- [TypeScript](https://www.typescriptlang.org/docs/home.html) knowledge
|
||||
- [Visual Studio Code Extension Authoring](https://code.visualstudio.com/api) knowledge
|
||||
|
||||
## Reporting Issues
|
||||
|
||||
Please report [openHAB VS Code Extension specific issues here](https://github.com/openhab/openhab-vscode/issues),
|
||||
while issues that are related to openHAB2 or Eclipse SmartHome should be reported in the
|
||||
while issues that are related to *openHAB2 addons* or *openHAB Core* should be reported in the
|
||||
[openHAB2 GitHub repository](https://github.com/openhab/openhab2-addons/issues) or the
|
||||
[Eclipse SmartHome GitHub repository](https://github.com/eclipse/smarthome), respectively.
|
||||
[openHAB Core GitHub repository](https://github.com/openhab/openhab-core), respectively.
|
||||
Do not worry, if you are not clear, which category your issue belongs to - we will
|
||||
redirect you, if necessary.
|
||||
|
||||
## What's in the folder
|
||||
|
||||
* This folder contains all of the files necessary for your extension
|
||||
* `package.json` - this is the manifest file in which you declare your extension and command.
|
||||
The sample plugin registers a command and defines its title and command name. With this information
|
||||
VS Code can show the command in the command palette. It doesn’t yet need to load the plugin.
|
||||
* `src/extension.ts` - this is the main file where you will provide the implementation of your command.
|
||||
- This folder contains all of the files necessary for the extension
|
||||
|
||||
- `package.json` - this is the manifest file in which most declarations for the extension capabilities are done.
|
||||
It defines which commands get registered for the extension, which languages get provided, which views are distributed to vscode,...
|
||||
For most new added features an adaption of package-json will be needed.
|
||||
|
||||
- In the `client` folder you can find everything related to features that are available for the user.
|
||||
|
||||
- In the `serverJS` folder you can find the implementation of our local language server, which communicates with client part in background.
|
||||
|
||||
- `client/src/extension.ts` - this is the main extension entry file where you will provide implementations regarding user features like code completion and Item/Things View are.
|
||||
The file exports one function, `activate`, which is called the very first time your extension is
|
||||
activated (in this case by executing the command). Inside the `activate` function we call `registerCommand`.
|
||||
We pass the function containing the implementation of the command as the second parameter to
|
||||
`registerCommand`.
|
||||
|
||||
- `snippets` provides autopcompletion snippets which add predefined templates in the editor
|
||||
|
||||
- `meta` holds some metadata like the langauage definition that is needed for syntax highlighting
|
||||
|
||||
- `.azure-pipelines` holds the configuration we are using for our *continous integration*.
|
||||
You can find our builds and artifacts on https://dev.azure.com/openhab/vscode-openhab/_build?definitionId=2
|
||||
|
||||
- `webpack`: We use webpack for bundling this extension. The config is shared over different locations. It has a shared part in the repository root which is then used by specific parts for each sub package. In this case `client` and `serverJS` have their own webpack config files.
|
||||
|
||||
## Get up and running straight away
|
||||
|
||||
* Clone your fork of this repository
|
||||
* (Optionally) create a new branch addressing an [open issue](https://github.com/openhab/openhab-vscode/issues)
|
||||
* From the command line run `code` in the project folder
|
||||
* Press `F5` to open a new window with your extension loaded
|
||||
* In the new window (`[Extension Development Host]` in the title) open your openHAB config folder
|
||||
* Set breakpoints in your code inside `src/extension.ts` to debug your extension
|
||||
* Find output from your extension in the debug console
|
||||
- Clone your fork of this repository
|
||||
- (Optionally) create a new branch addressing an [open issue](https://github.com/openhab/openhab-vscode/issues)
|
||||
- From the command line run `code` in the project folder
|
||||
- Press `F5` to open a new window with your extension loaded
|
||||
- In the new window (`[Extension Development Host]` in the title) open your openHAB config folder
|
||||
- Set breakpoints in your code inside `src/extension.ts` to debug your extension
|
||||
- Find output from your extension in the debug console
|
||||
|
||||
## Make changes
|
||||
|
||||
* You can relaunch the extension from the debug toolbar after changing code in `src/extension.ts`
|
||||
* You can also reload (`Ctrl+R` or `Cmd+R` on Mac) the VS Code window with your extension to load your changes
|
||||
- You can relaunch the extension from the debug toolbar after changing code in `src/extension.ts`
|
||||
- You can also reload (`Ctrl+R` or `Cmd+R` on Mac) the VS Code window with your extension to load your changes
|
||||
|
||||
## Explore the API
|
||||
|
||||
* You can open the full set of our API when you open the file `node_modules/vscode/vscode.d.ts`
|
||||
- You can open the full set of our API when you open the file `node_modules/vscode/vscode.d.ts`
|
||||
|
||||
## Run tests
|
||||
|
||||
* Open the debug viewlet (`Ctrl+Shift+D` or `Cmd+Shift+D` on Mac) and from the launch configuration dropdown pick `Launch Tests`
|
||||
* Press `F5` to run the tests in a new window with your extension loaded
|
||||
* See the output of the test result in the debug console
|
||||
* Make changes to `test/extension.test.ts` or create new test files inside the `test` folder
|
||||
* By convention, the test runner will only consider files matching the name pattern `**.test.ts`
|
||||
* You can create folders inside the `test` folder to structure your tests any way you want
|
||||
- Open the debug viewlet (`Ctrl+Shift+D` or `Cmd+Shift+D` on Mac) and from the launch configuration dropdown pick `Launch Tests`
|
||||
- Press `F5` to run the tests in a new window with your extension loaded
|
||||
- See the output of the test result in the debug console
|
||||
- **TBD** Make changes to `test/extension.test.ts` or create new test files inside the `test` folder
|
||||
- By convention, the test runner will only consider files matching the name pattern `**.test.ts`
|
||||
- You can create folders inside the `test` folder to structure your tests any way you want
|
||||
|
||||
|
||||
## Contribution guidelines
|
||||
|
|
@ -74,9 +89,9 @@ to do everything for everybody. This means that we might decide against
|
|||
incorporating a new feature. However, there might be a way to implement
|
||||
that feature *on top of* openHAB.
|
||||
|
||||
### Discuss your design on the mailing list
|
||||
### Discuss your design on the forum
|
||||
|
||||
We recommend discussing your plans [in the discussion forum](https://community.openhab.org/c/organisation/code)
|
||||
We recommend discussing your plans [in the discussion forum](https://community.openhab.org/c/apps-services/vs-code)
|
||||
before starting to code - especially for more ambitious contributions.
|
||||
This gives other contributors a chance to point you in the right
|
||||
direction, give feedback on your design, and maybe point out if someone
|
||||
|
|
@ -113,7 +128,7 @@ your documentation changes for clarity, concision, and correctness, as
|
|||
well as a clean documentation build.
|
||||
|
||||
Write clean code. Universally formatted code promotes ease of writing, reading,
|
||||
and maintenance.
|
||||
and maintenance.
|
||||
|
||||
Pull requests descriptions should be as clear as possible and include a
|
||||
reference to all the issues that they address.
|
||||
|
|
@ -138,11 +153,6 @@ same commit so that a revert would remove all traces of the feature or fix.
|
|||
Commits that fix or close an issue should include a reference like `Closes #XXX`
|
||||
or `Fixes #XXX`, which will automatically close the issue when merged.
|
||||
|
||||
Add your name to the AUTHORS file, but make sure the list is sorted and your
|
||||
name and email address match your git configuration. The AUTHORS file is
|
||||
regenerated occasionally from the git commit history, so a mismatch may result
|
||||
in your changes being overwritten.
|
||||
|
||||
### Merge approval
|
||||
|
||||
openHAB maintainers use LGTM (Looks Good To Me) in comments on the code review
|
||||
|
|
@ -206,27 +216,20 @@ then you just add a line to every git commit message:
|
|||
|
||||
using your real name (sorry, no pseudonyms or anonymous contributions.)
|
||||
|
||||
One way to automate this, is customise your get ``commit.template`` by adding
|
||||
a ``prepare-commit-msg`` hook to your openHAB checkout:
|
||||
|
||||
```
|
||||
curl -L -o .git/hooks/prepare-commit-msg https://raw.github.com/openhab/openhab2/master/contrib/prepare-commit-msg.hook && chmod +x .git/hooks/prepare-commit-msg
|
||||
```
|
||||
|
||||
* Note: the above script expects to find your GitHub user name in ``git config --get github.user``
|
||||
- Note: the above script expects to find your GitHub user name in ``git config --get github.user``
|
||||
|
||||
#### Small patch exception
|
||||
|
||||
There are several exceptions to the signing requirement. Currently these are:
|
||||
|
||||
* Your patch fixes spelling or grammar errors.
|
||||
* Your patch is a single line change to documentation.
|
||||
- Your patch fixes spelling or grammar errors.
|
||||
- Your patch is a single line change to documentation.
|
||||
|
||||
### How can I become a maintainer?
|
||||
|
||||
* Step 1: learn the component inside out
|
||||
* Step 2: make yourself useful by contributing code, bugfixes, support etc.
|
||||
* Step 3: volunteer on [the discussion group](https://community.openhab.org/c/organisation/code) or on [GitHub](https://github.com/openhab/openhab-vscode/issues?labels=question&page=1&state=open)
|
||||
- Step 1: learn the component inside out
|
||||
- Step 2: make yourself useful by contributing code, bugfixes, support etc.
|
||||
- Step 3: volunteer on [the discussion group](https://community.openhab.org/c/organisation/code) or on [GitHub](https://github.com/openhab/openhab-vscode/issues?labels=question&page=1&state=open)
|
||||
|
||||
Don't forget: being a maintainer is a time investment. Make sure you will have time to make yourself available.
|
||||
You don't have to be a maintainer to make a difference on the project!
|
||||
|
|
@ -237,20 +240,20 @@ We want to keep the openHAB community awesome, growing and collaborative. We
|
|||
need your help to keep it that way. To help with this we've come up with some
|
||||
general guidelines for the community as a whole:
|
||||
|
||||
* Be nice: Be courteous, respectful and polite to fellow community members: no
|
||||
- Be nice: Be courteous, respectful and polite to fellow community members: no
|
||||
regional, racial, gender, or other abuse will be tolerated. We like nice people
|
||||
way better than mean ones!
|
||||
|
||||
* Encourage diversity and participation: Make everyone in our community
|
||||
- Encourage diversity and participation: Make everyone in our community
|
||||
feel welcome, regardless of their background and the extent of their
|
||||
contributions, and do everything possible to encourage participation in
|
||||
our community.
|
||||
|
||||
* Keep it legal: Basically, don't get us in trouble. Share only content that
|
||||
- Keep it legal: Basically, don't get us in trouble. Share only content that
|
||||
you own, do not share private or sensitive information, and don't break the
|
||||
law.
|
||||
|
||||
* Stay on topic: Make sure that you are posting to the correct channel
|
||||
- Stay on topic: Make sure that you are posting to the correct channel
|
||||
and avoid off-topic discussions. Remember when you update an issue or
|
||||
respond to an email you are potentially sending to a large number of
|
||||
people. Please consider this before you update. Also remember that
|
||||
|
|
|
|||
68
README.md
68
README.md
|
|
@ -1,11 +1,11 @@
|
|||
# openHAB VS Code Extension
|
||||
|
||||
[](https://dev.azure.com/openhab/vscode-openhab/_build?definitionId=2)
|
||||
[](https://dev.azure.com/openhab/vscode-openhab/_build?definitionId=2)
|
||||
[](https://opensource.org/licenses/EPL-2.0)
|
||||
[](https://marketplace.visualstudio.com/items?itemName=openhab.openhab&ssr=false#review-details)
|
||||
[](https://marketplace.visualstudio.com/items?itemName=openhab.openhab)
|
||||
[](https://github.com/openhab/openhab-vscode/releases)
|
||||
[![Azure DevOps builds (branch)][ADOBuildBadgeImage]][ADOBuildBadgeImageLink]
|
||||
[![Azure DevOps tests (branch)][ADOTestImage]][ADOTestImageLink]
|
||||
[![EPL-2.0][LicenseBadgeImage]][LicenseBadgeImageLink]
|
||||
[![Visual Studio Marketplace Rating][MarketplaceRatingBadgeImage]][MarketplaceRatingBadgeImageLink]
|
||||
[![Visual Studio Marketplace Downloads)][MarketplaceDownloadBadgeImage]][MarketplaceDownloadBadgeImageLink]
|
||||
[![GitHub release][GitHubReleaseBadge]][GitHubReleaseBadgeLink]
|
||||
|
||||
[openHAB](http://www.openhab.org) is a vendor and techology agnostic open source automation software for your home. This [Visual Studio Code](https://code.visualstudio.com) extension allows you to work with openHAB configuration files (like `*.items`, `*.rules`, `*.sitemap` and `*.script`) thanks to the syntax highlighting, code snippets and integrated search.
|
||||
|
||||
|
|
@ -13,23 +13,22 @@ The extension is designed with openHAB 2.x in mind - most snippets and design pa
|
|||
|
||||
## Features
|
||||
|
||||
* Syntax highlighting for the [openHAB DSL](https://www.openhab.org/docs/configuration/) (rules, items, scripts and sitemaps).
|
||||
* Code snippets for openHAB, including [Design Patterns](https://community.openhab.org/tags/designpattern) by Rich Koshak
|
||||
* Integrated quick search of [openHAB Community](https://community.openhab.org)
|
||||
* Integrated Basic UI (or Classic UI) browser window (`Ctrl + Alt + O` or editor title icon)
|
||||
* Integrated Paper UI preview for the Items and Things
|
||||
* Integration with openHAB REST API
|
||||
* List of all Items accessible from the tree view
|
||||
* Code completions
|
||||
* Language Server Protocol support - syntax validation
|
||||
* Dynamic Items creation from Thing's channels
|
||||
* Quick Karaf console access
|
||||
* Add Items to Sitemap with one click
|
||||
- Syntax highlighting for the [openHAB DSL](https://www.openhab.org/docs/configuration/) (rules, items, scripts and sitemaps).
|
||||
- Code snippets for openHAB, including [Design Patterns](https://community.openhab.org/tags/designpattern) by Rich Koshak
|
||||
- Integrated quick search of [openHAB Community](https://community.openhab.org)
|
||||
- Integrated Basic UI (or Classic UI) browser window (`Ctrl + Alt + O` or editor title icon)
|
||||
- Integrated Paper UI preview for the Items and Things
|
||||
- Integration with openHAB REST API
|
||||
- List of all Items accessible from the tree view
|
||||
- Code completions
|
||||
- Language Server Protocol support - syntax validation
|
||||
- Dynamic Items creation from Thing's channels
|
||||
- Quick Karaf console access
|
||||
- Add Items to Sitemap with one click
|
||||
- Get live Item states while hovering over item names in the Editor
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## Configuration
|
||||
|
||||
Learn more about the configuration options in our [documentation](https://github.com/openhab/openhab-vscode/blob/master/docs/USAGE.md) on github.
|
||||
|
|
@ -52,9 +51,34 @@ See [CHANGELOG.md](https://github.com/openhab/openhab-vscode/blob/master/CHANGEL
|
|||
|
||||
----
|
||||
|
||||
## Contributing
|
||||
|
||||
Everyone is invited to improve this extension.
|
||||
|
||||
Check out the extension code in our [GitHub repository](https://github.com/openhab/openhab-vscode/).
|
||||
See [Contributing.md](https://github.com/openhab/openhab-vscode/blob/master/CONTRIBUTING.md) file for further technical and formal details for contributing something to the openHAB project.
|
||||
|
||||
### For More Information
|
||||
|
||||
* [openHAB Documentation](https://www.openhab.org/docs/)
|
||||
* [openHAB Community](https://community.openhab.org)
|
||||
- [openHAB Documentation](https://www.openhab.org/docs/)
|
||||
- [openHAB Community](https://community.openhab.org)
|
||||
|
||||
**Enjoy!**
|
||||
|
||||
[ADOBuildBadgeImage]: https://img.shields.io/azure-devops/build/openhab/82e39b03-2e63-4a34-84ca-3cb57be32202/2/master?logo=azure-pipelines&logoColor=blue
|
||||
[ADOBuildBadgeImageLink]: https://dev.azure.com/openhab/vscode-openhab/_build?definitionId=2
|
||||
|
||||
[ADOTestImage]: https://img.shields.io/azure-devops/tests/openhab/82e39b03-2e63-4a34-84ca-3cb57be32202/2/master?logo=azure-devops&logoColor=blue
|
||||
[ADOTestImageLink]: https://dev.azure.com/openhab/vscode-openhab/_build?definitionId=2
|
||||
|
||||
[LicenseBadgeImage]: https://img.shields.io/badge/license-EPL%202-green.svg (License Information)
|
||||
[LicenseBadgeImageLink]: https://opensource.org/licenses/EPL-2.0
|
||||
|
||||
[MarketplaceRatingBadgeImage]: https://img.shields.io/visual-studio-marketplace/stars/openhab.openhab?color=orange&label=marketplace&logo=visual-studio-code&logoColor=blue (Star rating)
|
||||
[MarketplaceRatingBadgeImageLink]: https://marketplace.visualstudio.com/items?itemName=openhab.openhab&ssr=false#review-details
|
||||
|
||||
[MarketplaceDownloadBadgeImage]: https://img.shields.io/visual-studio-marketplace/d/openhab.openhab?logo=visual-studio-code&logoColor=blue
|
||||
[MarketplaceDownloadBadgeImageLink]: https://marketplace.visualstudio.com/items?itemName=openhab.openhab
|
||||
|
||||
[GitHubReleaseBadge]: https://img.shields.io/github/v/release/openhab/openhab-vscode?include_prereleases (latest by date including pre-releases)
|
||||
[GitHubReleaseBadgeLink]: https://github.com/openhab/openhab-vscode/releases
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 1.1 MiB |
Loading…
Reference in New Issue