🤝 Contributing to Mushroom Strategy

We love contributions from the community! Whether you're reporting a bug, suggesting a new feature, or submitting code changes, your help makes the Mushroom Strategy better for everyone.

Please take a moment to review this guide before making a contribution.

📜 Code of Conduct

To ensure a welcoming and inclusive environment, all contributors are expected to adhere to our Code of Conduct. Please read it carefully.

🐞 Reporting Bugs

Found a bug? That's not ideal, but your report helps us squash it!

Check existing issues: Before opening a new issue, please search our GitHub Issues or Discussions to see if the bug has already been reported.
Open a new issue: If it's a new bug, please open a new issue.
Provide details: In your report, please include:

A clear and concise description of the bug.
Steps to reproduce the behavior.
Expected behavior.
Screenshots or animated GIFs (if applicable).
Your Home Assistant version and Mushroom Strategy version.

✨ Suggesting Features

Have a great idea for a new feature or enhancement? We'd love to hear it!

Check existing suggestions: Search our GitHub Issues or Discussions to see if the feature has already been requested.
Open a new issue: If it's a new idea, open a new issue.
Describe your idea: Clearly explain the feature, why you think it's useful, and any potential use cases.

💻 Contributing Code

Want to get your hands dirty with the code? Awesome! We appreciate all code contributions.

Fork the Repository: Start by forking the DigiLive/mushroom-strategy repository to your own GitHub account.

Clone Your Fork: Clone your forked repository to your local machine.

git clone https://github.com/YOUR_USERNAME/mushroom-strategy.git
cd mushroom-strategy

Create a New Branch: Create a new branch for your feature or bug fix. Use a descriptive name (e.g., feature/my-awesome-feature, bugfix/fix-admonition-rendering).
```
git checkout -b feature/my-new-feature
```
Set up Development Environment:

Ensure you have Node.js and npm installed.
Install project dependencies: npm install
You can build the strategy with npm run build (for production) or npm run build-dev (for development/testing).
Copy the built files to your Home Assistant's www/community/mushroom-strategy folder for testing.

Make Your Changes: Implement your bug fix or new feature.
Test Your Changes: Thoroughly test your changes to ensure they work as expected and don't introduce new issues.
Commit Your Changes:

We follow Conventional Commits for clear commit history.
Example: feat: add new card option or fix: correct card rendering issue
```
git add .
git commit -m "feat: add super cool new feature"
```

Push to Your Fork:
```
git push origin feature/my-new-feature
```
Create a Pull Request (PR):

Go to your forked repository on GitHub.
You should see a prompt to create a pull request from your new branch to the main branch of DigiLive/mushroom-strategy.
Provide a clear title and description for your PR, referencing any related issues.
Be prepared to discuss your changes and address any feedback during the review process.

📄 Improving Documentation

Good documentation is vital! If you find typos, unclear sections, or want to add more examples, please open a pull request. The documentation is located in the docs/ folder of this repository.

🌐 Translations

Help us make Mushroom Strategy accessible to more users around the world by contributing and improving translations!

Language tags have to follow BCP 47.
A list of most language tags can be found here: IANA subtag registry. Examples: fr, fr-CA, zh-Hans.

Check for Existing Translations: See if your language is already being worked on or exists.
Locate Translation Files: Language files are found within the src/translations directory. Each language has its own locale.json file (e.g., en.json, nl.json, pt-BR.json).
Create or Update:

To create a new language: Copy an existing .json file (e.g., en.json), rename it to your language code (e.g., de.json for German), and translate the property values.
To update an existing language: Open the .json file for your language and update any missing or outdated translations.

Submit a Pull Request: Once your translations are complete, submit a pull request with your changes. Clearly state which language you are contributing to or updating.

!!! info Integrating a new Translation:

* For your new language file to be picked up, it needs to be imported and registered at file
  `src/utilities/localize.ts`.
* You will need to add an `import` statement for your new `.json` file at the top, following the existing pattern.
* Then, you'll need to add it to the `languages` map, associating the language code with the imported module.

**Special Handling for `language-country` Locales:**  
If you are adding a country-specific locale (e.g., `es-ES` for Spanish (Spain) or `en-GB` for English 
(United Kingdom)), you should create a file like `en-GB.json` in the `translations` folder. In 
`src/utilities/localize.ts`, you'll import it similarly and add it to the `languages` map using the full locale 
code.  
Please ensure you follow existing patterns for `language-country` codes, which typically use a hyphen (`-`) + a 
UPPER-cased country code in the file name and an underscore (`_`) + a lower-cased country code in the import key.  

!!! example
    ```typescript
    import * as en from '../translations/en.json';
    import * as pt_br from '../translations/pt-BR.json';
    
    /** Registry of currently supported languages */
    const languages: Record<string, unknown> = {
    en,
    'pt-BR': pt_br,
    };
    ```

🙏 Get Support

If you have questions about contributing or need help with your setup, please open a discussion on our GitHub repository.

6.9 KiB Raw Blame History