diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..379e613 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,155 @@ +# Contributing to weewx-me.teo + +First off, thank you for considering contributing to weewx-me.teo! Contributions from the community are essential in +making this project better. Whether you want to report a bug, propose new features, improve documentation, add +translations, or submit code changes, I welcome your input and assistance. This guide will help you get started with +contributing. + +## Development Environment + +This is a [Next.js](https://nextjs.org) project bootstrapped with +[`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app). + +### Getting Started + +First, install the dependencies: + +```bash +npm install --force +``` + +> [!IMPORTANT] +> The skin uses NextJS v15, which has a peer dependency on React v19 RC, which makes many packages fail to +> install because of peer dependency mismatch. Right now, `npm install --force` must be used to work around this, but +> hopefully React v19 will be out of RC soon and that workaround won't be needed anymore. + +Then, run the development server: + +```bash +npm run dev +``` + +Then, open [http://localhost:3000](http://localhost:3000) with your browser to see the result. + +### Data Flow + +- The skin uses a hybrid approach combining static generation and client-side updates +- The NextJS app is pre-compiled and served as a static site +- Weather data is generated by the WeeWX report engine in the `data/*.json` files +- These JSON files are fetched by the client-side app, reloaded automatically every minute +- When running the development server, the skin will use sample data from the `public/sample_data` directory. + +### Architecture Diagram + +```mermaid +architecture-beta + group users(cloud)[Users] + group skin(cloud)[weewx_me_teo] + group weewx(cloud)[WeeWX] + + service nextjs(server)[NextJS app] in skin + service sample(disk)[Sample JSON data] in skin + service json(disk)[JSON data files] in weewx + service html(disk)[HTML files] in weewx + service cheetah(server)[Cheetah templates] in weewx + + service visitor(internet)[External visitor] in users + service developer(internet)[Developer] in users + + visitor:R -- L:html + html:R -- L:json + + developer:R -- L:nextjs + nextjs:R -- L:sample + + nextjs:B --> T:html + cheetah:T --> B:json +``` + +### NextJS + +To learn more about Next.js, take a look at the following resources: + +- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API. +- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial. + +You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions +are welcome! + +## Adding New Languages + +1. [Fork](https://github.com/bourquep/weewx-me.teo/fork) this repository +2. Create a new code translation file in `messages/xx.json` +3. Copy the template from `en.json` +4. Translate all strings +5. Create a new skin translation file in `weewx/skins/me.teo/lang/xx.json` +6. Copy the template from `en.json` +7. Translate all strings +8. Add the language code to: + - the `build-locale` language matrix in `.github/workflows/ci.yml` + - the `CopyGenerator.copy_once` list in `weewx/skins/me.teo/skin.conf` +9. Add the language to the list of supported languages in `README.md` +10. Submit a pull request and be a hero! + +## Submitting Pull Requests + +### Conventional Commits + +This repository uses [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/). This means that each commit +message must follow a specific format. The format is as follows: + +``` +[optional scope]: +``` + +The `type` must be one of the following: + +| Type | Description | +| ---------- | ---------------------------------------------------------------------------------- | +| `feat` | A new feature. | +| `fix` | A bug fix. | +| `docs` | Documentation only changes. | +| `perf` | A code change that improves performance. | +| `refactor` | A code change that neither fixes a bug nor adds a feature. | +| `style` | Changes that do not affect the meaning of the code (white-space, formatting, etc). | +| `chore` | Regular maintenance tasks and updates. | +| `build` | Changes that affect the build system or external dependencies. | +| `ci` | Changes to CI configuration files and scripts. | +| `revert` | Reverting a previous commit. | + +The `scope` is optional and should be used to specify the part of the codebase that the commit affects. + +The `description` should be a short, concise summary of the changes made in the commit. The description will appear +as-is in the release notes, so make sure it is clear, informative and not too technical. + +For example: + +``` +feat: Added support for dark mode +``` + +### Semantic Versioning + +This repository uses [semantic versioning](https://semver.org/). This means that each release will be versioned +according to the following rules: + +- Increment the major version for breaking changes +- Increment the minor version for new features +- Increment the patch version for bug fixes + +Releases are automatically generated by [semantic-release](https://github.com/semantic-release/semantic-release) based +on the commit messages. The version number is determined by the type of commits since the last release. + +### Code Style + +This repository uses [ESLint](https://eslint.org/) and [Prettier](https://prettier.io/) to enforce code style and +formatting. Please make sure that your code follows the linting rules and conventions used in the project. + +### Pull Request Checklist + +Before submitting a pull request, please make sure that: + +- Your code follows the coding standards and conventions used in the project +- The documentation has been updated to reflect any changes +- Your commit messages follow the conventional commits format +- Your changes do not introduce any new linting errors or warnings diff --git a/README.md b/README.md index 057f91d..50c2571 100644 --- a/README.md +++ b/README.md @@ -28,6 +28,10 @@ You will need a working WeeWX installation. So far, this skin has only been test ### Standard Installation +> [!IMPORTANT] +> You **do not** need to clone this repository to install the skin. The following instructions will guide +> you through the simple installation process. + 1. Run the following command on your WeeWX server: ```bash @@ -110,91 +114,9 @@ When configuring your web server, you can either: If the latter approach is used, please be aware that the observation and unit labels will still be displayed according to the settings in `weewx.conf`. -## Developer's Guide - -This is a [Next.js](https://nextjs.org) project bootstrapped with -[`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app). - -### Getting Started - -First, install the dependencies: - -```bash -npm install --force -``` - -> [!IMPORTANT] -> The skin uses NextJS v15, which has a peer dependency on React v19 RC, which makes many packages fail to -> install because of peer dependency mismatch. Right now, `npm install --force` must be used to work around this, but -> hopefully React v19 will be out of RC soon and that workaround won't be needed anymore. - -Then, run the development server: - -```bash -npm run dev -``` - -Then, open [http://localhost:3000](http://localhost:3000) with your browser to see the result. - -### Data Flow - -- The skin uses a hybrid approach combining static generation and client-side updates -- The NextJS app is pre-compiled and served as a static site -- Weather data is generated by the WeeWX report engine in the `data/*.json` files -- These JSON files are fetched by the client-side app, reloaded automatically every minute -- When running the development server, the skin will use sample data from the `public/sample_data` directory. - -### Architecture Diagram - -```mermaid -architecture-beta - group users(cloud)[Users] - group skin(cloud)[weewx_me_teo] - group weewx(cloud)[WeeWX] - - service nextjs(server)[NextJS app] in skin - service sample(disk)[Sample JSON data] in skin - service json(disk)[JSON data files] in weewx - service html(disk)[HTML files] in weewx - service cheetah(server)[Cheetah templates] in weewx - - service visitor(internet)[External visitor] in users - service developer(internet)[Developer] in users - - visitor:R -- L:html - html:R -- L:json - - developer:R -- L:nextjs - nextjs:R -- L:sample - - nextjs:B --> T:html - cheetah:T --> B:json -``` - -### Adding New Languages - -1. [Fork](https://github.com/bourquep/weewx-me.teo/fork) this repository -2. Create a new code translation file in `messages/xx.json` -3. Copy the template from `en.json` -4. Translate all strings -5. Create a new skin translation file in `weewx/skins/me.teo/lang/xx.json` -6. Copy the template from `en.json` -7. Translate all strings -8. Add the language code to: - - the `build-locale` language matrix in `.github/workflows/ci.yml` - - the `CopyGenerator.copy_once` list in `weewx/skins/me.teo/skin.conf` -9. Add the language to the list of supported languages in `README.md` -10. Submit a pull request and be a hero! - -### NextJS - -To learn more about Next.js, take a look at the following resources: - -- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API. -- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial. +## Contributing -You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions -are welcome! +If you want to contribute to this project, please read the [CONTRIBUTING.md](CONTRIBUTING.md) file for guidelines. ## License