Docs: Added README and contributing guide #124
82
CONTRIBUTING.md
Normal file
@@ -0,0 +1,82 @@
|
||||
# Contributing guide
|
||||
|
||||
## Type of contributing
|
||||
|
||||
There are two main types of contributions, accepted in KolibriOS:
|
||||
|
Burer marked this conversation as resolved
Outdated
|
||||
|
||||
- Submitting issues about problems in project
|
||||
- Submitting code to project via pull requests
|
||||
|
||||
Each of these types is described in details below.
|
||||
|
Burer marked this conversation as resolved
Outdated
dunkaist
commented
Both these types are ? > Each of these types is
Both these types are ?
|
||||
|
||||
## Issues
|
||||
|
||||
You can help us by submitting issues about problems, found in system. Currently, there are two main ways of submitting an issue in the project: **Bug Reports** and **Feature Requests**:
|
||||
|
||||
- Bug Reports are suitable if you find a **bug** (crash, error, inexcpected behaviour) in some part of the system (kernel, drivers, apps etc.) and want to report it
|
||||
- Feature Request are used, when you wont to propose some **improvement** to the system (missing features, impoved user experience, etc.)
|
||||
|
Burer marked this conversation as resolved
Outdated
dunkaist
commented
Feature Request_s_
improved user (only one space between the words) > Feature Request
Feature Request_s_
> improved user
improved user (only one space between the words)
|
||||
|
||||
## Pull requests
|
||||
|
||||
You can also help us by submitting code via pull requests. The process of submitting a pull request consists of following steps:
|
||||
|
||||
1. Find what you want to implement or improve
|
||||
2. Make a fork of kolibrios repository
|
||||
3. Create a branch with a name that matches your changes
|
||||
4. Implement and test the changes
|
||||
5. Create commits according to the [accepted style](##commit-style)
|
||||
|
mxlgv marked this conversation as resolved
Outdated
Sweetbread
commented
Incorrect anchor link Incorrect anchor link
Burer
commented
Fixed. Fixed.
|
||||
6. Create and submit a pull request into main branch
|
||||
7. Wait for CI/CD pipelines and code review to pass
|
||||
|
||||
When a pull request is submitted, at least two project participants must conduct a code review, after which the proposed changes can be corrected (if it's necessary) and merged into the project.
|
||||
|
Burer marked this conversation as resolved
Outdated
dunkaist
commented
changes need to be corrected (if requested) > changes can be corrected (if it's necessary)
changes need to be corrected (if requested)
|
||||
|
||||
## Commit style
|
||||
|
||||
### Pattern
|
||||
|
Burer marked this conversation as resolved
Outdated
dunkaist
commented
Message pattern? > Pattern
Message pattern?
|
||||
|
||||
The commit message should look like this:
|
||||
|
||||
```test
|
||||
[Category] Commit message header
|
||||
|
mxlgv marked this conversation as resolved
Outdated
Sweetbread
commented
-> -> `commit type`(`category`): `commit message`
To [Conventional Commit Messages](https://gist.github.com/rishavpandey43/84665ffe3cea76400d8e5a1ad7133a79)
dunkaist
commented
I have checked Linux, Qemu and GCC. They all do mention categories but in a plain format like 'category: Commit message'. I believe it would be easier for us to explain to people why they should follow a policy if it is the policy of Linux, Qemu and GCC rather than the one of Rishav Pandey. I have checked [Linux](https://web.git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=90fd9ad5b0c981693c8512d9da01f14fb6596e9d), [Qemu](https://gitlab.com/qemu-project/qemu/-/commit/2f3b6e61f692bade441230dd25c1c0f101bd2eef) and [GCC](https://gcc.gnu.org/git/?p=gcc.git;a=commit;h=254549d2bb9bb3c2719dec597427919c59514fc3). They all do mention categories but in a plain format like 'category: Commit message'. I believe it would be easier for us to explain to people why they should follow a policy if it is the policy of Linux, Qemu and GCC rather than the one of Rishav Pandey.
Sweetbread
commented
https://www.conventionalcommits.org/en/v1.0.0/
https://www.conventionalcommits.org/en/v1.0.0/
> **Why Use Conventional Commits**
> - Automatically generating CHANGELOGs.
> - Automatically determining a semantic version bump (based on the types of commits landed).
> - Communicating the nature of changes to teammates, the public, and other stakeholders.
> - Triggering build and publish processes.
> - Making it easier for people to contribute to your projects, by allowing them to explore a more structured commit history.
dunkaist
commented
I might be wrong but this looks like whishful thinking to me.
All the automatically generated changelogs I have seen are unreadable because you have to know the context first to understand them. They can be used if you want to have them as a formality only. But they won't be useful for users/developers as a dump of commit messages.
To what version in KolibriOS does this apply?
The nature of changes is described in any normal commit message.
Currently we build and publish on each push. What will this change?
I have never seen anybody using it. I might be wrong but this looks like whishful thinking to me.
> Automatically generating CHANGELOGs.
All the automatically generated changelogs I have seen are unreadable because you have to know the context first to understand them. They can be used if you want to have them as a formality only. But they won't be useful for users/developers as a dump of commit messages.
> Automatically determining a semantic version bump (based on the types of commits landed).
To what version in KolibriOS does this apply?
> Communicating the nature of changes to teammates, the public, and other stakeholders.
The nature of changes is described in any normal commit message.
> Triggering build and publish processes.
Currently we build and publish on each push. What will this change?
> Making it easier for people to contribute to your projects, by allowing them to explore a more structured commit history.
I have never seen anybody using it.
Sweetbread
commented
If commit messages are descriptive, follow a consistent format, and include meaningful context, the generated changelog can be more useful.
Not neccessary the OS, but apps, libs and other software in it
The standart enforse to use types, which is better both for describing and searching in commit list
For example, not to build if the type is
Namida, antimicrox, AGS, yazi, bubbletea, pokete, Bagels, kaizen, fd > All the automatically generated changelogs I have seen are unreadable because you have to know the context first to understand them
If commit messages are descriptive, follow a consistent format, and include meaningful context, the generated changelog can be more useful.
> To what version in KolibriOS does this apply?
Not neccessary the OS, but apps, libs and other software in it
> The nature of changes is described in any normal commit message.
The standart enforse to use types, which is better both for describing and searching in commit list
> Currently we build and publish on each push. What will this change?
For example, not to build if the type is `docs`
> I have never seen anybody using it.
[Namida](https://github.com/namidaco/namida), [antimicrox](https://github.com/AntiMicroX/antimicrox), [AGS](https://github.com/Aylur/ags), [yazi](https://github.com/sxyazi/yazi), [bubbletea](https://github.com/charmbracelet/bubbletea), [pokete](https://github.com/lxgr-linux/pokete), [Bagels](https://github.com/EnhancedJax/Bagels), [kaizen](https://github.com/TheRiceCold/kaizen), [fd](https://github.com/sharkdp/fd)
dunkaist
commented
I wish we could eventually motivate people to write meaningful commit messages. Let be honest, forcing them to choose from 20 commit types it just too much, it won't work. What is surprisingly strange, the spec allows to shorten feature as feat but not performance as perf, no logic behind this.
The rebuild is needed is the docs are in the distro. Tup handles this automatically already. You don't need to manually control this via commit messages.
I have never heard of them. Linux, Qemu and GCC are more familiar to our potential developers, I believe. > If commit messages are descriptive, follow a consistent format, and include meaningful context, the generated changelog can be more useful.
I wish we could eventually motivate people to write meaningful commit messages. Let be honest, forcing them to choose from 20 commit types it just too much, it won't work. What is surprisingly strange, the spec allows to shorten feature as feat but not performance as perf, no logic behind this.
> For example, not to build if the type is docs
The rebuild is needed is the docs are in the distro. Tup handles this automatically already. You don't need to manually control this via commit messages.
> Namida, antimicrox, AGS, yazi, bubbletea, pokete, Bagels, kaizen, fd
I have never heard of them. Linux, Qemu and GCC are more familiar to our potential developers, I believe.
mxlgv
commented
What GCC uses, Linux seems to me really more attractive What GCC uses, Linux seems to me really more attractive
mxlgv
commented
@Sweetbread @dunkaist The adoption of a style for commits can take a long time (while we are discussing we don't have any documentation at all). This minimal documentation with very light rules should be enough for the community while it adapts to GIT. We can probably raise this issue in the future. But for now, let's not get hung up on it. This PR contains other changes as well. @Sweetbread @dunkaist The adoption of a style for commits can take a long time (while we are discussing we don't have any documentation at all). This minimal documentation with very light rules should be enough for the community while it adapts to GIT. We can probably raise this issue in the future. But for now, let's not get hung up on it. This PR contains other changes as well.
|
||||
|
||||
Commit message body, if needed
|
||||
```
|
||||
|
||||
|
mxlgv marked this conversation as resolved
Outdated
rgimad
commented
Text seems like too formal For example, instead of this, you can simply write smth like
Text seems like too formal
For example, instead of this, you can simply write smth like
`Commit message should look like `
etc
mxlgv
commented
Fixed Fixed
|
||||
- Commit message header and body should reflect changes made in commit
|
||||
- Commit message header should start with a capital letter
|
||||
- Commit message body should be separated from the header by one empty line
|
||||
|
||||
### Length
|
||||
|
||||
Maximum number of characters in a commit header is **72** (standard for **Git**). Also, **72** is the maximum length of a line in a commit body.
|
||||
|
||||
### Categories
|
||||
|
||||
List of existing categories accepted in the project:
|
||||
|
||||
- `Krn` - kernel
|
||||
- `Drv` - drivers
|
||||
|
mxlgv marked this conversation as resolved
Outdated
dunkaist
commented
Why not 50 and 72 like in Linux? Why not 50 and 72 like in Linux?
mxlgv
commented
I thought about it but I didn't find any advantages. Rather, we limit ourselves. I thought about it but I didn't find any advantages. Rather, we limit ourselves.
|
||||
- `Libs` - libraries
|
||||
- `Apps` - user-space applications
|
||||
- `Skins` - skins
|
||||
- `Build` - build system
|
||||
- `CI/CD` - CI/CD
|
||||
- `Docs` - documentation
|
||||
- `Data` - images, configs, resources, etc.
|
||||
- `All` - global changes
|
||||
|
||||
If changes are made to a specific component, the name of the component separated by `/` character needs to be specified. For example:
|
||||
|
||||
```text
|
||||
Apps/shell
|
||||
|
Burer marked this conversation as resolved
Outdated
dunkaist
commented
instruction
familiar with (one space)
participate in the life of our project? > instructions
instruction
> familiar with
familiar with (one space)
> participate in the work of this project
participate in the life of our project?
|
||||
Libs/libimg
|
||||
```
|
||||
|
||||
## Merge commits
|
||||
|
||||
> [!WARNING]
|
||||
> Merge commits are **prohibited** in the project
|
||||
|
||||
## Conclusion
|
||||
|
||||
We hope this small instructions will help you to can common with KolibriOS contributon and inspire you to participate in the work of this project.
|
||||
28
README.md
Normal file
@@ -0,0 +1,28 @@
|
||||
# KolibriOS
|
||||
|
||||
[](./COPYING.TXT)
|
||||
[](https://git.kolibrios.org/KolibriOS/kolibrios/actions/workflows/build.yaml)
|
||||
|
||||
KolibriOS is a hobby operating system for x86-compatible computers, which is currently being developed by a small teem of enthusiasts.
|
||||
|
Burer marked this conversation as resolved
Outdated
dunkaist
commented
small but passionate (!)
team > small
small but passionate (!)
> teem
team
|
||||
|
||||
It's kernel is written entirely in [FASM](https://flatassembler.net/) assembly language, making it very compact and lean on system resources.
|
||||
|
Burer marked this conversation as resolved
Outdated
dunkaist
commented
Its
kernel, most drivers and many programs > It's
Its
> kernel
kernel, most drivers and many programs
|
||||
|
||||
Based on [MenuetOS](https://www.menuetos.net/), it uses its own standards and is NOT fully POSIX or UNIX compliant
|
||||
|
Burer marked this conversation as resolved
Outdated
dunkaist
commented
compliant. (dot) > compliant
compliant. (dot)
|
||||
|
||||
## Contributing
|
||||
|
||||
We would appreciate any participation in the project and always welcome new users and contributors.
|
||||
|
||||
Detailed instructions for the contribution process can be found in the [contributing guide](./CONTRIBUTING.md).
|
||||
|
||||
Common list of tasks, issues and enhancement proposals can be found on [this page](https://git.kolibrios.org/KolibriOS/kolibrios/issues).
|
||||
|
||||
## Special thanks
|
||||
|
||||
The KolibriOS team expresses special thanks to the author of the 32-bit **MenuetOS**, [Ville Turjanmaa](https://www.menuetos.net/contact.htm). We also want to note that all **MenuetOS** copyrights have been preserved.
|
||||
|
||||
## License
|
||||
|
mxlgv marked this conversation as resolved
Outdated
mxlgv
commented
The license is already written next to Build system section. It seems that this is not necessary. @Burer @dunkaist @Sweetbread what do you think? The license is already written next to **Build system** section. It seems that this is not necessary.
@Burer @dunkaist @Sweetbread what do you think?
Burer
commented
I agree that we can remove License here, as it as already preset at the top of README. I agree that we can remove License here, as it as already preset at the top of README.
mxlgv
commented
Fixed Fixed
|
||||
|
||||
Contents of this repository are licensed under the terms of **GNU GPL 2.0** unless otherwise specified.
|
||||
|
||||
See [this](./kernel/trunk/COPYING.TXT) file for details.
|
||||
If we were talking about the entire KolibriOS then we should have mentioned documentation, testing, content creation, etc. Since we agreed in the telegram chat to write about this main repo only, let's change 'in KolibriOS' to 'to the main KolibriOS repository'.