120 lines
4.1 KiB
Markdown
120 lines
4.1 KiB
Markdown
# Contributing to iOwO
|
|
|
|
Before we get started, thank you for thinking about doing so!
|
|
|
|
## Through an issue
|
|
|
|
- Be excellent to each other. Adhere to the [code of conduct].
|
|
- About the title: If you had 5 seconds to tell someone the essence of the issue, what would it be?
|
|
|
|
### Bugs
|
|
|
|
- Write out in detail which steps in which order are necessary to reproduce the bug.
|
|
- Include environmental information as well, in specific:
|
|
- How did you install iOwO?
|
|
- What version of iOwO are you running?
|
|
- What operating system are you running?
|
|
In the case of a Linux distro, mention the specific distro and when you last updated as well.
|
|
- If the bug causes a crash, try to get a backtrace or in worse cases, a coredump.
|
|
|
|
### Feature requests
|
|
|
|
- Be sure to include a motivation in which case your intended feature would be used
|
|
even if it seems obvious to you.
|
|
- Estimate what would be needed to implement the feature:
|
|
- Is it an addition to the language itself?
|
|
- Is it just a new command?
|
|
- Does it ground-breakingly change how iOwO works?
|
|
|
|
## Through a PR
|
|
|
|
1. Clone the repo.
|
|
2. Switch to a new appropiately named branch for what you want to do, using `git switch -c`.
|
|
3. Implement your code changes with your favorite code editor.
|
|
4. Try them with `cargo run`.
|
|
5. If there are errors or warnings, go to step 3. Commit occasionally.
|
|
6. Otherwise,
|
|
- if you have an account at https://forge.katzen.cafe,
|
|
1. fork the repo
|
|
2. set it up as a remote using `git remote add`
|
|
3. push using `git push @ -u`
|
|
- if you don't,
|
|
1. combine your patches using `git diff --patch` and throw them in a file
|
|
2. send that file to one of the maintainers per email
|
|
- alongside with a description of what it does
|
|
3. also mention in the mail that we should consider GitHub and GitLab mirrors,
|
|
referring to this line
|
|
|
|
### Tech stack
|
|
|
|
The techstack we operate on is
|
|
|
|
- [typst] for documents and concrete proposals
|
|
- [Rust] for the actual code
|
|
|
|
So if you want to contribute functionality, take a look at [The Rust Programming Language book]!
|
|
If you want to contribute thoughts and technical designs, then consider taking a ride through
|
|
[typst's excellent tutorial]!
|
|
|
|
For creative things, we suggest using whatever **you** are comfortable with.
|
|
Otherwise, we suggest these:
|
|
|
|
- [Inkscape], [GIMP] and [Blender] for promotional material like logos and posters
|
|
- [Penpot] for layouting prototypes and the like
|
|
|
|
[typst]: https://typst.app
|
|
[Rust]: https://www.rust-lang.org
|
|
[The Rust Programming Language book]: https://doc.rust-lang.org/book/
|
|
[typst's excellent tutorial]: https://typst.app/docs/tutorial
|
|
|
|
[Inkscape]: https://inkscape.org/
|
|
[GIMP]: https://www.gimp.org/
|
|
[Blender]: https://www.blender.org/
|
|
[Penpot]: https://penpot.app/
|
|
|
|
## Politics
|
|
|
|
- Current maintainers are defined as the entities listed in the [code of conduct]
|
|
|
|
### PRs
|
|
|
|
- Every PR requires an approving review from a maintainer (that is not the author) before merge
|
|
- Maintainers can merge their own PRs
|
|
- But only after approval
|
|
|
|
### Major decisions
|
|
|
|
- All current maintainers have to agree **unanimously**.
|
|
- Agreement must be based on [informed consent].
|
|
- In effect, a maintainer has to understand what they agree to.
|
|
|
|
# Interacting with PRs
|
|
|
|
Remember, be respectful.
|
|
Entities invest their free time and motivation into making these changes,
|
|
treat them appropiately.
|
|
|
|
- Since in iOwO, we mostly work based on forks, [git's remotes] work fairly good.
|
|
- Replace things in pointy brackets (`<>`) respectively (and remove the pointy brackets).
|
|
|
|
## Initial steps for a new contributor or new local checkout
|
|
|
|
```sh
|
|
git remote add <contributor-name> https://forge.katzen.cafe/<contributor-account>/iowo.git
|
|
git remote update <contributor-name>
|
|
```
|
|
|
|
## After setting up the remote
|
|
|
|
- You can repeat this step anytime you want to switch branches or update your local checkout.
|
|
- The PR branch is visible just below the PR title on Forgejo, after the colon (`:`).
|
|
|
|
```sh
|
|
git switch <pr-branch>
|
|
git pull
|
|
```
|
|
|
|
|
|
[code of conduct]: ./CODE_OF_CONDUCT.md
|
|
[informed consent]: https://en.wikipedia.org/wiki/Informed_consent
|
|
[git's remotes]: https://git-scm.com/docs/git-remote
|