mirror of
https://github.com/Bismuth-Forge/bismuth.git
synced 2024-11-04 13:37:43 +03:00
141 lines
4.4 KiB
Markdown
141 lines
4.4 KiB
Markdown
<!--
|
|
SPDX-FileCopyrightText: 2021 Mikhail Zolotukhin <mail@genda.life>
|
|
SPDX-License-Identifier: MIT
|
|
-->
|
|
|
|
# 🤝 Contributing
|
|
|
|
We glad, that you want to contribute to the project. To make things easier please read the
|
|
following.
|
|
|
|
## 🏗️ Development packages
|
|
|
|
To make sure you can develop the script install all the tools you need:
|
|
|
|
- [REUSE tool](https://git.fsfe.org/reuse/tool#install)
|
|
- [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)
|
|
|
|
## 👷 Prepare environment
|
|
|
|
To prepare environment, clone the project and execute the following:
|
|
|
|
```sh
|
|
npm install # Install development dependencies
|
|
npm run prepare # Install Git hooks
|
|
```
|
|
|
|
This will install all the things you need, including TypeScript compiler, Unit Testing
|
|
framework and so fore so on.
|
|
|
|
The last command will install Git pre-commit hooks you will need, such as automatic
|
|
REUSE validation and autoformatting.
|
|
|
|
## 🔨 Compile the script
|
|
|
|
To compile the script execute the following:
|
|
|
|
```sh
|
|
npm run build
|
|
```
|
|
|
|
This will compile the script via TypeScript and produce the JS output adapted to
|
|
[QML Javascript Environment](https://doc.qt.io/qt-5/qtqml-javascript-hostenvironment.html).
|
|
|
|
## 📦 Packaging and installation
|
|
|
|
To create a package from the compiled output run:
|
|
|
|
```sh
|
|
npm run package
|
|
```
|
|
|
|
This will produce a `.kwinscript` package, useful for installation in KWin Scripts KCM.
|
|
But you can actually automate the installation process via script:
|
|
|
|
```sh
|
|
npm run script-install
|
|
```
|
|
|
|
Note however, that if you have the script already installed and enabled, you need to
|
|
restart KWin, so that it can apply the changes you've made. To do so you have a
|
|
convenient script too:
|
|
|
|
```sh
|
|
npm run install-and-restart-kwin-x11
|
|
```
|
|
|
|
This will run the previous steps for you and restart KWin, if you're using X11 session.
|
|
After you quit the restarted KWin, it will automatically restart in the background, so
|
|
that you working session remains in tact.
|
|
|
|
## 🧪 Unit testing
|
|
|
|
Bismuth comes with unit tests. To run them execute the standard npm command:
|
|
|
|
```sh
|
|
npm test
|
|
```
|
|
|
|
There is an important note, regarding the unit testing. All the tests are run
|
|
on the Node.js environment. Basically, it means that the global environment you
|
|
see in unit-tests and the global environment you see in the script, while it is
|
|
running in KWin scripting environment, are not the same. Because of this we
|
|
minimize the usage of global object in the code, and you should do the same.
|
|
|
|
## 📑 API Documentation generation
|
|
|
|
To generate API docs, run the following:
|
|
|
|
```sh
|
|
npm run docs
|
|
```
|
|
|
|
This will generate the documentation via TypeDoc in the build directory.
|
|
|
|
## 😥 This seems complicated
|
|
|
|
Don't worry. The npm commands from the above depend on each other. That means
|
|
that in a typical development workflow you will need only to run of them.
|
|
For example, if I want to manually test the script after some changes, I run:
|
|
|
|
```sh
|
|
npm run install-and-restart-kwin-x11
|
|
```
|
|
|
|
This commands will automatically build the script, package it, install it and
|
|
restart the KWin, so that I can see the changes. No need to worry about the
|
|
steps.
|
|
|
|
## ❓ FAQ
|
|
|
|
### I already installed Bismuth, but I don't want to replace it with development version
|
|
|
|
Bismuth can be temporarily loaded via KWin DBus API without installing:
|
|
|
|
```sh
|
|
npm run start
|
|
npm run stop
|
|
```
|
|
|
|
Note that Bismuth can destroy itself completely once it is disabled, so no
|
|
restart is required to deactivated it.
|
|
|
|
### I am not a developer
|
|
|
|
Do not worry, you can still contribute fixing the documentation or just opening
|
|
the issues and reporting bugs! Do not underestimate your impact, as the job of
|
|
tester and bug triager is one of the most valuable in any software project.
|
|
What the use of being a developer if you don't know what to fix or implement?
|
|
|
|
### What skills do I need to contribute as a developer?
|
|
|
|
Bismuth is written in TypeScript, so you'll have to know some. To learn it, check out
|
|
the [Handbook](https://www.typescriptlang.org/docs/handbook/). If you know JavaScript
|
|
and have an experience in some strongly typed language, it will be easy, and even if
|
|
it not, you're still doing a great job - you can do it!
|
|
|
|
You'll also need to know something about KWin scripting and Qt JavaScript Environment.
|
|
For KWin scripting there is [a tutorial on the KDE developer portal](https://develop.kde.org/docs/plasma/kwin/).
|
|
And for Qt JavaScript things you can check out
|
|
[the official documentation](https://doc.qt.io/qt-5/qtqml-javascript-hostenvironment.html).
|