Thank you for contributing to this repository, your help is greatly appreciated ! In ordrer to keep the project clear and make the contribution process as easy as possible, please read this contribution guide and follow the described guidelines.
Development workflow and tools
perseid
releases follow semantic versioning.
master
is the main branch, and contains latest stable code that passes all the tests. We generate
new releases from this banch only. Please do not push your code directly on master
, open a
pull request first so it can be validated by the community. Branches should be named after the
issue they fix, such as issue-<ISSUE_ID>
, so it is easier for everyone to understand what they
are meant for. If there is no related issue, please open one (see below).
Feel free to open an issue on this repository, I will reply as soon as I can. You can also contact me directly on:
In order to improve issues management and to make information clearer and easily identifiable, a set of pre-defined labels has been created. Those labels are strictly structured in three main groups, each group giving a particular useful information about the issue. It means that for each issue you open, you must assign it exactly one label of each group, and update them all along the issue lifecycle as it evolves.
- type: breaking change: suggestion for a breaking change, that should be part of a next major release.
- type: bug: bug reporting, that should be fixed in the next patch.
- type: regression: just like bug, except it just showed up in the last release, and must be fixed in the next patch.
- type: enhancement: improvement that should be implemented in the next patch.
- type: feature: request for a new feature, that should be added in the next minor release.
- type: question: question or request for information, which can also help us to improve the documentation.
- type: discussion: everything else you want to discuss regarding the project.
- status: duplicate: another existing issue is treating about the same topic, and should be considered instead.
- status: in progress: somebody is currently working on this issue, and should (hopefully) perform a PR soon!
- status: invalid: issue is either dead, not reproductible, or does not follow the process, and will be closed soon.
- status: need more information: issue is too vague and cannot be managed without further information.
- status: new: issue was just submitted, and should be assigned to someone ASAP.
- status: unconfirmed: issue should be considered carefully to determine either it is a real issue or anything else.
- difficulty: starter: issue is pretty straightforward, and can be fixed by anyone (good first issue).
- difficulty: medium: issue is a bit complex, and requires some knowledge about the project.
- difficulty: challenging: issue is very complex, and requires both good skills and a deep knowledge of the project.
If you think you found a bug in the code, you can open an issue to report it, so the community can then work to fix it. Before opening a new issue, make sure the topic is not already being discussed in another issue, to prevent duplicates. Try to be as clear and exhaustive as possible, so people can quickly understand what is going on. You can use the following guidelines:
- Issue title explaining the bug in a small and concise sentence.
- Version on which you are experiencing the bug.
- Test case to reproduce the bug. You can link a JSFiddle, JSBin, CodePen or any other code snippet to help.
- Steps to reproduce if you don't have any test case link, you can provide a step-by-step process to reproduce the bug.
- Expected behaviour describing what should normally happen.
- Actual behaviour describing what actually happens.
- Additional information like comments, images, GIFs, anything that can help community to correct the issue...
Of course, don't forget to set the correct labels to your issue.
As for bugs, feel free to suggest any interesting improvement or new feature. Again, before opening this kind of request, make sure it is not already a work in progress by checking first the issues list. You can as well use a similar guideline as the one describe before to make a new request. Just keep in mind that other contributors have to understand your idea to put it into code.
Ready to contribute to the code? That is great, thank you and welcome in the contributors team! You can create a new branch and open a new pull request to propose your code to the community.
As for branches name, you should name your pull requests accordingly with the issue they solve
(e.g. issue-164
). If you wish to give additional information related to that issue, you can fill
the pull request description.
To technically contribute to this project, here are the software you will need:
- A UNIX terminal and an IDE ;)
- git
- docker
- docker-compose
git clone git@github.com:openizr/perseid.git
cd perseid
cp .env.example .env
- Fill or change environment variables in your
.env
file if necessary docker-compose --profile core up
to run@perseid/core
related containersdocker-compose --profile jobs up
to run@perseid/jobs
related containersdocker-compose --profile all up
to run all containersdocker exec -it <PROJECT_NAME>_<jobs|core> sh -c "yarn run test -w"
if you want to run unit testsdocker exec -it <PROJECT_NAME>_examples sh -c "yarn && yarn run dev"
if you want to run examples
This will run the project locally and allow you to develop and see changes in real-time.
In order to keep this package up-to-date, dependencies updates should be checked and updated regularily,
using the yarn outdated
and yarn upgrade-interactive --latest
commands.
Here is the list of repositories changelogs to watch for updates, for each package:
- @nabla/vite-plugin-eslint
- @sveltejs/vite-plugin-svelte
- @types/node
- @typescript-eslint/eslint-plugin
- @typescript-eslint/parser
- @vitejs/plugin-react
- @vitejs/plugin-vue
- @vitest/coverage-v8
- autoprefixer
- chokidar
- esbuild
- esbuild-plugin-vue-next
- esbuild-svelte
- eslint
- eslint-config-airbnb
- eslint-plugin-import
- eslint-plugin-jsx-a11y
- eslint-plugin-react
- eslint-plugin-react-hooks
- eslint-plugin-svelte
- eslint-plugin-vue
- eslint-plugin-vitest-globals
- fs-extra
- jsdom
- postcss
- postcss-sort-media-queries
- rollup
- rollup-plugin-visualizer
- sass
- svelte-check
- svelte-preprocess
- typescript
- typedoc
- vite
- vitest
- @types/react
- @types/react-dom
- @testing-library
- @testing-library/react
- @testing-library/svelte
- @testing-library/vue
- coveralls
- react
- react-dom
- svelte
- typescript-dev-kit
- vue
You don't have to worry about deploying the code and publishing it on npm
, the CI/CD system does
it for you (using Github Actions). Each time a new release is created on the master
branch, Github Actions
will automatically build and deploy this release on npm
with the version you specified in your
release name. Of course, all tests must pass otherwise code won't be deployed. However, if you want
to get an preview of the distributed package, you can run docker exec <PROJECT_NAME>_<PACKAGE> yarn run build
.
Assets will be compiled into the dist
directory of the proper package.
perseid
codebase follows the AirBnB Javascript Style Guide.
Several IDE extensions are available to automatically lint your code whenever you save files.
To provide good and clear git commit messages, you should follow these guidelines.
Project is structured as follow:
packages
: contains the actual packages codebasesexamples
: contains a bunch of code samples and tutorials for each package
Copyright (c) Openizr. All Rights Reserved.