Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
101 lines (78 loc) · 5.47 KB

CONTRIBUTING.md

File metadata and controls

101 lines (78 loc) · 5.47 KB
Raw

Contributing

Thank you for investing your time in contributing to our project! Any contribution you make will be reflected on the next release of MeteoalarmCard.

How to report bugs and propose new features

If you spot a problem in the project or want to propose a improvement or new integration to the project. Search if an issue already exists. If a related issue doesn't exist, you can open a new issue.

Setup local environment

If you don't have MeteoalarmCard running locally please follow this setup guide.

  1. Install newest LTS release of Node.js and the pnpm package manager.
  2. Fork this repository using Fork button. This will create a new repository on your account named <your username>/MeteoalarmCard
  3. Clone this repo to wherever you want: 
    git clone https://github.com/<your username>/MeteoalarmCard.git
  4. Go into the repo folder: 
    cd MeteoalarmCard
  5. Install dependencies (Node.js and pnpm are required): 
    pnpm install
  6. Run the development server in the first terminal. It's going to watch source files, recompile on changes and serve the compiled card on http://localhost:5000. 
    pnpm start

Now pick where you want to see the card render. Either way the dev server rebuilds on save, so you refresh the browser tab to pick up your changes.

Option A: the bundled Home Assistant (recommended)

Spins up a preconfigured instance of Home Assistant with the bundled integrations and a development dashboard. The integrations pull live data, so most cards show No active warnings unless there is real weather somewhere. Every pnpm run dev starts from scratch, so anything you change in the Home Assistant UI is gone on the next run.

  1. Install Docker with the Compose plugin.
  2. Run the Docker containers. The first boot may take a couple of minutes, it will download ~2 GB of images and needs internet access. 
    pnpm run dev
  3. Open http://localhost:8123. You should auto-login to the preconfigured Home Assistant instance. Open MeteoalarmCard in the sidebar.

Commands:

  • pnpm run dev:down stops the instance and deletes hass-dev/config

Option B: your own Home Assistant

Use this if you already run Home Assistant and want the card next to your real entities.

  1. Add http://localhost:5000/meteoalarm-card.js to your Lovelace Resources as a JavaScript Module.
  2. Add a Meteoalarm Card to any dashboard.

Your browser is what loads the file, so this works as long as you browse Home Assistant from the machine running pnpm start.

How to contribute

  1. Fork the project and clone it to your local machine. Follow the setup guide.
  2. Before making any changes pull from the remote repository to update your main branch 
       git pull upstream master
  3. Create a branch on which you will be working. 
        git checkout -b update-polish-translation
  4. Commit your changes and push it to your fork of the repository.
  5. Make sure your changes are working locally. Run pnpm run lint to check code style, pnpm test to run the tests and pnpm run build to build the card.
  6. Create a Pull Request (PR). Make sure to describe the changes that you made and use the Fixes: #number keyword if you were working on a issue.

How to add translations

We are currently looking to implement more languages to MeteoalarmCard. If you are able to add or improve translations in language you speak don't hastate to make a PR.

Notes about current translation keys

  • editor.error - These keys may use the {expected_entities_count} and {selected_entities_count} placeholders, which are replaced with the number of entities the integration expects and the number you selected. Never translate a placeholder - copy it exactly, including the braces. You can leave one out if your sentence doesn't need it.
  • editor.disable_swiper - If there is not a good translation for swiper you can keep this word untranslated.
  • editor.description - These keys are used to generate helpful description for users selecting entities. Please make sure they sound correctly in all combinations. The formula is start + any middle key + end
  • editor.description.warning_watch_statement_advisory - If there is not a good translation for words (warning, watch, statement, advisory) you can keep these words untranslated.

If you want to improve existing translation:

  1. Follow the setup guide and contributing guide
  2. Modify the language file in the src/localize/languages directory
  3. Remember that key that are not yet translated have null instead of the string. Please replace them with translated messages.
  4. Open a Pull Request.

If you want to create a new translation:

  1. Follow the setup guide and contributing guide
  2. Copy src/localize/languages/en.json file and name it with appropriate language code.
  3. Translate only the keys (second quotation mark).
  4. Import your translation in src/localize/localize.ts file.
  5. Mention your translation in README.md file (list should be sorted alphabetically).
  6. Open a Pull Request.