docs: some initial groundwork #2
Loading…
Reference in a new issue
No description provided.
Delete branch ":initial-docs"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
not much to say here yet i guess, as discussed on matrix and hedgedoc
oh no i forgor to write the CONTRIBUTING.md specifying we need one approving review to merge stuff, whatever, i'll do it later
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...
Personally I'd suggest
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
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
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.
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
Operators, to me at least, have the implication of being one or two characters long and usually special chars. How about "instruction" instead?
This is ready to look at, content-wise. I'll furthermore
justfile
to use nushell insteadCONTRIBUTING.md
to check out PRs@ -0,0 +19,4 @@
- algebraic enums
- traits (`Numeric`...)
= Execution stages
I really dislike using the word
execution
here, as it's a very common trigger word. Do you have any alternative ideas?Parsing? Evaluation? Interpretation?
Those are all individual phases of execution.
Hm. Thinking about it,
Evaluation
seems generic enough. I'll use that then.fwiw we may need to introduce a
docs/util
folder sometime in the future as well, as I believe especially the graph drawing utils indocs/design/util/graphics.typ
to be useful in proposals as wellInstructions 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?
Sounds good to me. Although then we'll need to differentiate between instructions and functions in the stages.
What value is gained by differentiating between functions and instructions?
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.
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?
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.
Then I'll just leave the distinction in the document and use instructions in the graph IR PR for now.
I'd suggest doing AST things once we actually started working on the language
What is missing before we could merge this? Basically every PR currently made depends on this.
Uhhh... don't think anything?
Then I'd appreciate a review!
(fwiw please don't merge if you happen to approve — need to rebase onto main first)
890cf0c65e
toe986f0fc1d
(ok did that)
@ -0,0 +3,4 @@
- [@Schrottkatze](https://forge.katzen.cafe/schrottkatze)
- [@multisamplednight](https://forge.katzen.cafe/multisamplednight)
- @iota-xSK
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.
@ -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.
Maybe replace the dot with a colon, that feels more correct due to the following enumeration
Tbh then I'd rather completely remove the dots at the end, would that be fine, too?
I meant specifically in the last thingy, like this:
@ -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
thing for the future: potential both way mirrors if that's possible? so we can accept contributions from gitlab and github...
@ -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
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
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.
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)
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.
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.
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.
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.
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
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.
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 still haven't quite understood how the suggestions are bad.
(and no, I won't accept "just remove them")
Of course it can't.
It sounds like we use exactly these tools and only these tools to me.
In
666b4f9cb6
I re-ordered the wording a bit, in order to make clear that this is only a suggestion. Is that fine?@ -0,0 +84,4 @@
# Interacting with PRs
> [!NOTE] Remember, be respectful.
is this supposed to render a certain way? it just shows the
[!NOTE]
when renderedIt does in some markdown viewers such as Obsidian or GitHub, but apparently not on Forgejo. I'll remove it then.
@ -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 (`:`).
Forgejo with a capital F since this is a document (so ig spelling is important) and forgejo is a name mew
@ -0,0 +7,4 @@
subtitle: [don't worry, we're just dreaming],
)
= Type data model
I think we should remove this entire section from this document for now, since I'm working on this in a different document
@ -0,0 +21,4 @@
= Execution stages
#graphics.stages-overview
This is fine, probably something we can work on further as the project progresses though and it gets more complex...
@ -0,0 +55,4 @@
The foundation of actually "doing" something.
- Can have any, even infinite, amount of inputs and outputs.
This is why I proposed using lists, dictionaries etc. in #4, to make this easier/cleaner
@schrottkatze Thank you for the review!
@ -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
typo:
@ -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.
The highlighted "you're* feels a bit, maybe split it into "you are" and highlight the "you"? (small nitpicky wording thing lol)
@ -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.
that reads a bit weird to me, maybe rephrase to:
I think this is ready to merge then!