katzen-cafe/iowo
2
4
Fork 1
Code Issues 4 Pull requests 2 Projects Releases Packages Wiki Activity

docs: some initial groundwork #2

Merged
multisamplednight merged 26 commits from :initial-docs into main 2024-01-20 19:00:52 +00:00
Conversation 25 Commits 26 Files changed 13 +96
2 changed files with 96 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files
Showing only changes of commit 32b547f9fa - Show all commits

11
CODE_OF_CONDUCT.md Normal file
View file

@ -0,0 +1,11 @@
See https://www.rust-lang.org/policies/code-of-conduct.
The current maintainers, that is,
- [@Schrottkatze](https://forge.katzen.cafe/schrottkatze)
- [@multisamplednight](https://forge.katzen.cafe/multisamplednight)
- @iota-xSK
multisamplednight marked this conversation as resolved Outdated
schrottkatze commented 2024-01-18 18:45:02 +00:00
Outdated
Review
Copy link

Remove her, as she stated to me that she does not want to be listed there and is not sure whether she wants to be an active maintainer.

Remove her, as she stated to me that she does not want to be listed there and is not sure whether she wants to be an active maintainer.
are the entities to email, message or talk to if you feel like any interaction in the context of
iOwO is not okay. We'll try to answer as soon as we can.
Please do **not** open an issue. Notify the maintainers privately instead.

85
CONTRIBUTING.md Normal file
View file

@ -0,0 +1,85 @@
# 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 update 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.
multisamplednight marked this conversation as resolved Outdated
schrottkatze commented 2024-01-18 18:47:20 +00:00
Outdated
Review
Copy link

Maybe replace the dot with a colon, that feels more correct due to the following enumeration

Maybe replace the dot with a colon, that feels more correct due to the following enumeration
multisamplednight commented 2024-01-18 21:25:39 +00:00
Outdated
Review
Copy link

Tbh then I'd rather completely remove the dots at the end, would that be fine, too?

Tbh then I'd rather completely remove the dots at the end, would that be fine, too?
schrottkatze commented 2024-01-18 22:45:16 +00:00
Outdated
Review
Copy link

I meant specifically in the last thingy, like this:

- 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?
I meant specifically in the last thingy, like this: ``` - 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? ```
- 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
multisamplednight marked this conversation as resolved Outdated
schrottkatze commented 2024-01-18 18:49:38 +00:00
Outdated
Review
Copy link

thing for the future: potential both way mirrors if that's possible? so we can accept contributions from gitlab and github...

thing for the future: potential both way mirrors if that's possible? so we can accept contributions from gitlab and github...
### Tech stack
The techstack we operate on is
- [typst] for documents and concrete proposals
- [Rust] for the actual code
- [Inkscape], [GIMP] and [Blender] for promotional material like logos and posters
schrottkatze commented 2024-01-18 18:51:17 +00:00
Outdated
Review
Copy link

Do we really need to list this this way? maybe rather a line that mentions that we use typst for design documentation? the fact that we use rust is quite obvious, and the rest is also just... up to whoever works with the respective things

Do we really need to list this this way? maybe rather a line that mentions that we use typst for design documentation? the fact that we use rust is quite obvious, and the rest is also just... up to whoever works with the respective things
multisamplednight commented 2024-01-18 21:31:47 +00:00
Outdated
Review
Copy link

They are not necessary. In fact, the whole file is not necessary.

However, it serves a different purpose: It tries to lend a helping hand to whatever contributor might come along, regardless of how much they might know to code, design or write yet. And in that case, no, it might not be obvious that we use Rust.

They are not necessary. In fact, the whole file is not necessary. However, it serves a different purpose: It tries to lend a helping hand to whatever contributor might come along, regardless of how much they might know to code, design or write yet. And in that case, no, it might not be obvious that we use Rust.
schrottkatze commented 2024-01-18 22:46:19 +00:00
Outdated
Review
Copy link

Yes, but someone interested in this tool will know about the open source tools, and if they wanna get involved with whatever, they should ask the respective team beforehand anyway (or until then, we will have dedicated docs for everything)

Yes, but someone interested in this tool will know about the open source tools, and if they wanna get involved with whatever, they should ask the respective team beforehand anyway (or until then, we will have dedicated docs for everything)
multisamplednight commented 2024-01-19 02:06:20 +00:00
Outdated
Review
Copy link

Personally I believe it's unlikely we'll have any kind of teams, rather just a few maintainers and contributors. In both cases, with or without teams, answering the same questions every single time about the stack we're suggesting to use could become rather tedious. On the other hand: What exactly gets lost by including links to the tools here?

How does knowing about iOwO imply knowledge about other open-source tools? If I were to show this to a photographer or an artist who has never coded before, they could still be interested in contributing, and get a quick overview over the project and approach angles to help with this.

Personally I believe it's unlikely we'll have any kind of teams, rather just a few maintainers and contributors. In both cases, with or without teams, answering the same questions every single time about the stack we're suggesting to use could become rather tedious. On the other hand: What exactly gets lost by including links to the tools here? How does knowing about iOwO imply knowledge about other open-source tools? If I were to show this to a photographer or an artist who has never coded before, they could still be interested in contributing, and get a quick overview over the project and approach angles to help with this.
schrottkatze commented 2024-01-19 07:09:03 +00:00
Outdated
Review
Copy link

It's simply not relevant to the project yet.

We can take care of documenting the tools we use for branding when we actually have branding...

And with teams I meant more like

If we have 4 contributors and 3 of them work on one thing, a different one and 2 from the other thing work on sth else, then that'd be 2 teams according to the definition I meant. Just like, splitting of responsibilities something something.

It's simply not relevant to the project *yet*. We can take care of documenting the tools we use for branding when we actually *have* branding... And with teams I meant more like If we have 4 contributors and 3 of them work on one thing, a different one and 2 from the other thing work on sth else, then that'd be 2 teams according to the definition I meant. Just like, splitting of responsibilities something something.
multisamplednight commented 2024-01-19 11:04:54 +00:00
Outdated
Review
Copy link

I don't really see the harm the list could do, even if parts of it aren't used yet, but sure, whatever. I'll remove the list.

I don't really see the harm the list could do, even if parts of it aren't used yet, but sure, whatever. I'll remove the list.
multisamplednight commented 2024-01-19 11:06:49 +00:00
Outdated
Review
Copy link

Actually, if it's overkill or "not necessary" for now, then I'll just remove the whole file as well. Guess we can answer the questions manually instead.

Actually, if it's overkill or "not necessary" for now, then I'll just remove the whole file as well. Guess we can answer the questions manually instead.
schrottkatze commented 2024-01-19 11:50:01 +00:00
Outdated
Review
Copy link

Okay. Probably will have to write it again if we publisize the project then some day, but until then we have more then enough time

Okay. Probably will have to write it again if we publisize the project then some day, but until then we have more then enough time
multisamplednight commented 2024-01-19 11:53:02 +00:00
Outdated
Review
Copy link

Exactly. We'd need it to write again later on, and it'll likely contain very similar content. So why not keep the current version, even if it contains content that is not strictly necessary yet? There's no maintenance burden behind it.

Exactly. We'd need it to write again later on, and it'll likely contain very similar content. So why not keep the current version, even if it contains content that is not strictly necessary yet? There's no maintenance burden behind it.
schrottkatze commented 2024-01-19 11:58:03 +00:00
Outdated
Review
Copy link

I'd just remove the tool-list. Since it's just suggestions anyway. Or at least remove programs like inkscape, of which we won't have in-house custom files in the project. Yes, Ik that inkscape uses svg, but it just isn't necessary since you can always use other editors for those.

I'd just remove the tool-list. Since it's just suggestions anyway. Or at least remove programs like inkscape, of which we won't have in-house custom files in the project. Yes, Ik that inkscape uses svg, but it just isn't necessary since you can always use other editors for those.
multisamplednight commented 2024-01-19 12:47:40 +00:00
Outdated
Review
Copy link

I still haven't quite understood how the suggestions are bad.

  • As long as no creative work is done, I don't see how it could cause potential harm.
  • It does not restrict entities from using whatever they want.
  • Entities that might not know them now have something they could start with, instead of just looking at opaque files without any hint on the "how" they might've been created.

(and no, I won't accept "just remove them")

I still haven't quite understood how the suggestions are bad. - As long as no creative work is done, I don't see how it could cause potential harm. - It does not restrict entities from using whatever they want. - Entities that might not know them now have something they could start with, instead of just looking at opaque files without any hint on the "how" they might've been created. (and no, I won't accept "just remove them")
schrottkatze commented 2024-01-19 17:43:36 +00:00
Outdated
Review
Copy link

As long as no creative work is done, I don't see how it could cause potential harm.

Of course it can't.

It does not restrict entities from using whatever they want.

It sounds like we use exactly these tools and only these tools to me.

> As long as no creative work is done, I don't see how it could cause potential harm. Of course it can't. > It does not restrict entities from using whatever they want. It sounds like we use exactly these tools and only these tools to me.
multisamplednight commented 2024-01-20 12:42:11 +00:00
Outdated
Review
Copy link

In 666b4f9cb6 I re-ordered the wording a bit, in order to make clear that this is only a suggestion. Is that fine?

In https://forge.katzen.cafe/katzen-cafe/iowo/commit/666b4f9cb68d533a07721610e3108a895111d122 I re-ordered the wording a bit, in order to make clear that this is only a suggestion. Is that fine?
So if you want to contribute functionality, take a look at [The Rust Programming Language book]!
If you want to contribute thoughts and techincal designs, then consider taking a ride through
[typst's excellent tutorial]!
multisamplednight marked this conversation as resolved Outdated
schrottkatze commented 2024-01-20 15:51:23 +00:00
Outdated
Review
Copy link

typo:

-If you want to contribute thoughts and techincal designs, then consider taking a ride through
+If you want to contribute thoughts and technical designs, then consider taking a ride through
typo: ```diff -If you want to contribute thoughts and techincal designs, then consider taking a ride through +If you want to contribute thoughts and technical designs, then consider taking a ride through ```
If you want to contribute art or the like, do that in whatever **you** are most comfortable with!
[typst]: https://typst.app
multisamplednight marked this conversation as resolved Outdated
schrottkatze commented 2024-01-20 15:50:17 +00:00
Outdated
Review
Copy link

The highlighted "you're* feels a bit, maybe split it into "you are" and highlight the "you"? (small nitpicky wording thing lol)

-For creative things, we suggest using whatever **you're** comfortable with.
+For creative things, we suggest using whatever **you** are comfortable with.
The highlighted "you're* feels a bit, maybe split it into "you are" and highlight the "you"? (small nitpicky wording thing lol) ```diff -For creative things, we suggest using whatever **you're** comfortable with. +For creative things, we suggest using whatever **you** are comfortable with. ```
[Rust]: https://www.rust-lang.org
[Inkscape]: https://inkscape.org/
[GIMP]: https://www.gimp.org/
[Blender]: https://www.blender.org/
[The Rust Programming Language book]: https://doc.rust-lang.org/book/
[typst's excellent tutorial]: https://typst.app/docs/tutorial
## 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.
[code of conduct]: ./CODE_OF_CONDUCT.md
[informed consent]: https://en.wikipedia.org/wiki/Informed_consent