docs: some initial groundwork #2

Merged
multisamplednight merged 26 commits from :initial-docs into main 2024-01-20 19:00:52 +00:00
Collaborator

not much to say here yet i guess, as discussed on matrix and hedgedoc

not much to say here yet i guess, as discussed on matrix and hedgedoc
multisamplednight added 4 commits 2024-01-02 04:06:03 +00:00
multisamplednight requested review from schrottkatze 2024-01-02 04:06:17 +00:00
Author
Collaborator

oh no i forgor to write the CONTRIBUTING.md specifying we need one approving review to merge stuff, whatever, i'll do it later

oh no i forgor to write the CONTRIBUTING.md specifying we need one approving review to merge stuff, whatever, i'll do it later
Owner

We should decide on a toolset to use across the project.

Also, should we have discussions in issue/pr threads? I feel like that's better and more public, even though forgejo doesnt federate yet...

We should decide on a toolset to use across the project. Also, should we have discussions in issue/pr threads? I feel like that's better and more public, even though forgejo doesnt federate yet...
Author
Collaborator

Personally I'd suggest

  • for documents and longer-form stuff → typst
  • for meta-stuff → markdown
  • for the code itself → Rust
  • for build stuff → just (and a nix flake sometime in the future)
Personally I'd suggest - for documents and longer-form stuff → typst - for meta-stuff → markdown - for the code itself → Rust - for build stuff → just (and a nix flake sometime in the future)
Author
Collaborator

Tbh I don't think it really matters atm if we do discussions over forgejo or over Matrix. Matrix is a bit more comfy though

Tbh I don't think it really matters atm if we do discussions over forgejo or over Matrix. Matrix is a bit more comfy though
multisamplednight added 1 commit 2024-01-07 20:44:13 +00:00
Owner

the reason why I wanted discussions over forgejo is, so they're all public and organized. If someone, including ourselves, wanted to reference why we decided on something or why we did something the way we did, they can reference back to what we talked about.

Also, build stuff: just + nushell, and for build scripts inside the flake also nushell?

since nu is a statically typed language with proper error handling etc

also, I suggest using typst exclusively for design documentation.

usage and api documentation should be available as markdown, so we can easily make web documentation

the reason why I wanted discussions over forgejo is, so they're all public and organized. If someone, including ourselves, wanted to reference why we decided on something or why we did something the way we did, they can reference back to what we talked about. Also, build stuff: just + nushell, and for build scripts inside the flake also nushell? since nu is a statically typed language with proper error handling etc also, I suggest using typst exclusively for design documentation. usage and api documentation should be available as markdown, so we can easily make web documentation
Owner

About the tooling stuff:
I suggest adding Penpot, since I generally prefer penpot for design work. I don't use it for icons etc, that's indeed where I fall back to inkscape, but generally I prefer penpot for layouting etc.

Also, probably not gimp?

About the tooling stuff: I suggest adding Penpot, since I generally prefer penpot for design work. I don't use it for icons etc, that's indeed where I fall back to inkscape, but generally I prefer penpot for layouting etc. Also, probably not gimp?
multisamplednight added 1 commit 2024-01-09 09:22:53 +00:00
Author
Collaborator

About the tooling stuff:
I suggest adding Penpot, since I generally prefer penpot for design work. I don't use it for icons etc, that's indeed where I fall back to inkscape, but generally I prefer penpot for layouting etc.

Also, probably not gimp?

The given toolset was just a suggestion. For creative work, in effect entities will just use whatever they like. But sure, I'll adjust it.

> About the tooling stuff: > I suggest adding Penpot, since I generally prefer penpot for design work. I don't use it for icons etc, that's indeed where I fall back to inkscape, but generally I prefer penpot for layouting etc. > > Also, probably not gimp? The given toolset was just a suggestion. For creative work, in effect entities will just use whatever they like. But sure, I'll adjust it.
multisamplednight added 3 commits 2024-01-09 11:43:11 +00:00
Owner

I think that we should rename Commands to Operators (or something similar), since a "Command" implies an imperative environment like a shell (and yes, I originally used that term because this was inspired by nushell, and of course we'll do a repl, but that I don't want a repl to be the primary use case.)

About the inputs example, maybe seperate the 3 lines more clearly?

(and maybe place a few strategic page breaks)

I propose treating inputs and outputs as plain types, I'll write a proposal for signatures and type notation later and will open a PR for it.

Little side note, you made a clbuttic mistake: every mention of "ast" is getting highlighted, even if it's not referring to an ast but part of another word

I think that we should rename Commands to Operators (or something similar), since a "Command" implies an imperative environment like a shell (and yes, I originally used that term because this was inspired by nushell, and of course we'll do a repl, but that I don't want a repl to be the primary use case.) About the inputs example, maybe seperate the 3 lines more clearly? (and maybe place a few strategic page breaks) I propose treating inputs and outputs as plain types, I'll write a proposal for signatures and type notation later and will open a PR for it. Little side note, you made a clbuttic mistake: every mention of "ast" is getting highlighted, even if it's not referring to an ast but part of another word
Author
Collaborator

Operators, to me at least, have the implication of being one or two characters long and usually special chars. How about "instruction" instead?

Operators, to me at least, have the implication of being one or two characters long and usually special chars. How about "instruction" instead?
multisamplednight added 7 commits 2024-01-10 20:55:51 +00:00
Author
Collaborator

This is ready to look at, content-wise. I'll furthermore

  • rewrite justfile to use nushell instead
  • add instructions in CONTRIBUTING.md to check out PRs
This is ready to look at, content-wise. I'll furthermore - [x] rewrite `justfile` to use nushell instead - [x] add instructions in `CONTRIBUTING.md` to check out PRs
multisamplednight added 3 commits 2024-01-10 22:31:43 +00:00
multisamplednight added 1 commit 2024-01-10 22:35:50 +00:00
multisamplednight reviewed 2024-01-10 22:41:38 +00:00
@ -0,0 +19,4 @@
- algebraic enums
- traits (`Numeric`...)
= Execution stages
Author
Collaborator

I really dislike using the word execution here, as it's a very common trigger word. Do you have any alternative ideas?

I **really** dislike using the word `execution` here, as it's a very common trigger word. Do you have any alternative ideas?
Owner

Parsing? Evaluation? Interpretation?

Parsing? Evaluation? Interpretation?
Author
Collaborator

Those are all individual phases of execution.

Those are all individual phases of execution.
Author
Collaborator

Hm. Thinking about it, Evaluation seems generic enough. I'll use that then.

Hm. Thinking about it, `Evaluation` seems generic enough. I'll use that then.
multisamplednight marked this conversation as resolved
Author
Collaborator

fwiw we may need to introduce a docs/util folder sometime in the future as well, as I believe especially the graph drawing utils in docs/design/util/graphics.typ to be useful in proposals as well

fwiw we may need to introduce a `docs/util` folder sometime in the future as well, as I believe especially the graph drawing utils in `docs/design/util/graphics.typ` to be useful in proposals as well
Owner

Operators, to me at least, have the implication of being one or two characters long and usually special chars. How about "instruction" instead?

Instructions I'd prefer stay reserved for the actual instructions that the executors take in directly. We could, of course, go the boring way and just call them functions?

> Operators, to me at least, have the implication of being one or two characters long and usually special chars. How about "instruction" instead? Instructions I'd prefer stay reserved for the actual instructions that the executors take in directly. We could, of course, go the boring way and just call them functions?
Author
Collaborator

Sounds good to me. Although then we'll need to differentiate between instructions and functions in the stages.

Sounds good to me. Although then we'll need to differentiate between instructions and functions in the stages.
multisamplednight added 1 commit 2024-01-11 10:51:28 +00:00
Author
Collaborator

What value is gained by differentiating between functions and instructions?

What value is gained by differentiating between functions and instructions?
Owner

In the current stage of the project, there isn't. But functions are something that, IMO should be definable by users (in the language), so maybe instructions may just be a subset of functions, as in they're calleable with the same syntax. But that's language level.

In the current stage of the project, there isn't. But functions are something that, IMO should be definable by users (in the language), so maybe instructions may just be a subset of functions, as in they're calleable with the same syntax. But that's language level.
Owner

This probably isn't the technically correct term, but I'd say the scheduler or whatever also decides which executor does what, so they may be mixed.

Also, Idk if the graph is the AST already, since as I understand a AST is far closer to the start when interpreting/compiling code?

This probably isn't the technically correct term, but I'd say the scheduler or whatever also decides which executor does what, so they may be mixed. Also, Idk if the graph is the AST already, since as I understand a AST is far closer to the start when interpreting/compiling code?
Author
Collaborator

I found no fitting AST repr for the source code we're heading for atm. Though you're invited to share your thoughts on how one might look like.

I found no fitting AST repr for the source code we're heading for atm. Though you're invited to share your thoughts on how one might look like.
Author
Collaborator

In the current stage of the project, there isn't. But functions are something that, IMO should be definable by users (in the language), so maybe instructions may just be a subset of functions, as in they're calleable [sic] with the same syntax. But that's language level.

Then I'll just leave the distinction in the document and use instructions in the graph IR PR for now.

> In the current stage of the project, there isn't. But functions are something that, IMO should be definable by users (in the language), so maybe instructions may just be a subset of functions, as in they're calleable [sic] with the same syntax. But that's language level. Then I'll just leave the distinction in the document and use instructions in the graph IR PR for now.
Owner

I'd suggest doing AST things once we actually started working on the language

I'd suggest doing AST things once we actually started working on the language
Author
Collaborator

What is missing before we could merge this? Basically every PR currently made depends on this.

What is missing before we could merge this? Basically every PR currently made depends on this.
Owner

Uhhh... don't think anything?

Uhhh... don't think anything?
Author
Collaborator

Then I'd appreciate a review!

Then I'd appreciate a review!
Author
Collaborator

(fwiw please don't merge if you happen to approve — need to rebase onto main first)

(fwiw please don't merge if you happen to approve — need to rebase onto main first)
multisamplednight force-pushed initial-docs from 890cf0c65e to e986f0fc1d 2024-01-18 19:18:10 +00:00 Compare
Author
Collaborator

(ok did that)

(ok did that)
schrottkatze approved these changes 2024-01-18 21:22:09 +00:00
@ -0,0 +3,4 @@
- [@Schrottkatze](https://forge.katzen.cafe/schrottkatze)
- [@multisamplednight](https://forge.katzen.cafe/multisamplednight)
- @iota-xSK
Owner

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.
multisamplednight marked this conversation as resolved
CONTRIBUTING.md Outdated
@ -0,0 +21,4 @@
- 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.
Owner

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
Author
Collaborator

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?
Owner

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? ```
multisamplednight marked this conversation as resolved
CONTRIBUTING.md Outdated
@ -0,0 +41,4 @@
- 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
Owner

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...
multisamplednight marked this conversation as resolved
CONTRIBUTING.md Outdated
@ -0,0 +50,4 @@
- [typst] for documents and concrete proposals
- [Rust] for the actual code
- [Inkscape], [GIMP] and [Blender] for promotional material like logos and posters
- [Penpot] for layouting prototypes and the like
Owner

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
Author
Collaborator

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.
Owner

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)
Author
Collaborator

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.
Owner

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.
Author
Collaborator

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.
Author
Collaborator

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.
Owner

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
Author
Collaborator

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.
Owner

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.
Author
Collaborator

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")
Owner

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.
Author
Collaborator

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?
CONTRIBUTING.md Outdated
@ -0,0 +84,4 @@
# Interacting with PRs
> [!NOTE] Remember, be respectful.
Owner

is this supposed to render a certain way? it just shows the [!NOTE] when rendered

is this supposed to render a certain way? it just shows the `[!NOTE]` when rendered
Author
Collaborator

It does in some markdown viewers such as Obsidian or GitHub, but apparently not on Forgejo. I'll remove it then.

It does in some markdown viewers such as Obsidian or GitHub, but apparently not on Forgejo. I'll remove it then.
multisamplednight marked this conversation as resolved
CONTRIBUTING.md Outdated
@ -0,0 +101,4 @@
## 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 (`:`).
Owner

Forgejo with a capital F since this is a document (so ig spelling is important) and forgejo is a name mew

Forgejo with a capital F since this is a document (so ig spelling is important) and forgejo is a name mew
multisamplednight marked this conversation as resolved
@ -0,0 +7,4 @@
subtitle: [don't worry, we're just dreaming],
)
= Type data model
Owner

I think we should remove this entire section from this document for now, since I'm working on this in a different document

I think we should remove this entire section from this document for now, since I'm working on this in a different document
multisamplednight marked this conversation as resolved
@ -0,0 +21,4 @@
= Execution stages
#graphics.stages-overview
Owner

This is fine, probably something we can work on further as the project progresses though and it gets more complex...

This is fine, probably something we can work on further as the project progresses though and it gets more complex...
multisamplednight marked this conversation as resolved
@ -0,0 +55,4 @@
The foundation of actually "doing" something.
- Can have any, even infinite, amount of inputs and outputs.
Owner

This is why I proposed using lists, dictionaries etc. in #4, to make this easier/cleaner

This is why I proposed using lists, dictionaries etc. in #4, to make this easier/cleaner
multisamplednight marked this conversation as resolved
multisamplednight added 1 commit 2024-01-18 21:48:09 +00:00
Author
Collaborator

@schrottkatze Thank you for the review!

@schrottkatze Thank you for the review!
multisamplednight added 1 commit 2024-01-19 02:09:51 +00:00
multisamplednight added 1 commit 2024-01-20 12:40:26 +00:00
schrottkatze requested changes 2024-01-20 15:55:09 +00:00
CONTRIBUTING.md Outdated
@ -0,0 +53,4 @@
- [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 techincal designs, then consider taking a ride through
Owner

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 ```
multisamplednight marked this conversation as resolved
CONTRIBUTING.md Outdated
@ -0,0 +56,4 @@
If you want to contribute thoughts and techincal designs, then consider taking a ride through
[typst's excellent tutorial]!
For creative things, we suggest using whatever **you're** comfortable with.
Owner

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. ```
multisamplednight marked this conversation as resolved
multisamplednight added 1 commit 2024-01-20 17:24:01 +00:00
schrottkatze reviewed 2024-01-20 18:00:28 +00:00
CONTRIBUTING.md Outdated
@ -0,0 +94,4 @@
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.
Owner

that reads a bit weird to me, maybe rephrase to:

-- Since in iOwO, we mostly work based on forks, [git's remotes] work fairly good.
+- Since we mostly work using forks, [git's remotes] work fairly well.
that reads a bit weird to me, maybe rephrase to: ```diff -- Since in iOwO, we mostly work based on forks, [git's remotes] work fairly good. +- Since we mostly work using forks, [git's remotes] work fairly well. ```
multisamplednight marked this conversation as resolved
multisamplednight added 1 commit 2024-01-20 18:52:47 +00:00
schrottkatze approved these changes 2024-01-20 18:56:58 +00:00
schrottkatze left a comment
Owner

I think this is ready to merge then!

I think this is ready to merge then!
multisamplednight merged commit 92aa3b4a3a into main 2024-01-20 19:00:52 +00:00
multisamplednight deleted branch initial-docs 2024-01-20 19:00:52 +00:00
Sign in to join this conversation.
No reviewers
No labels
proposal
No milestone
No project
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference: katzen-cafe/iowo#2
No description provided.