mnemos workspace testing

jamesmunns commented 1 year ago

Hey all! Now that #532 has landed, I'm trying it out on mnemos. I thought I would add some experience reports.

All testing below is done with this repo (specific commit tagged).

JSON workspace config

First, I got a little confused about whether oranda was using JSON or JSON5. The docs include some // comments in the sample json, and due to using these comments and trailing commas, I originally was unable to get the current main branch to "notice" my oranda-workspace.json. I needed to go in and add more tracing output to finally get the error in Config::build_workspace_root(), because the ? on OrandaLayer::load(config_path)?; was swallowing the JSON error and the command line just said:

⚠ >o_o< WARNING: Ignoring Rust project, oranda is currently per-package and this looks like a whole workspace

It would be nice to have a "tried to read but failed" message here.

Workspace setup

Once I got the JSON stuff sorted, I was able to build a workspace project. Output looks like this (sorry, some of the tracing logs are mine):

➜  mnemos git:(main) ✗ ~/personal/oranda/target/release/oranda dev
⚠ >o_o< WARNING: root path => '"/Users/james/personal/mnemos"'
⚠ >o_o< WARNING: Does exist!
⚠ >o_o< WARNING: Loading...
⚠ >o_o< WARNING: config => 'Ok(Some(OrandaLayer { project: None, build: None, marketing: None, styles: None, components: None, workspace: Some(WorkspaceLayer { name: Some("MnemOS"), members: Some([WorkspaceMember { slug: "kernel", path: "./source/kernel" }, WorkspaceMember { slug: "abi", path: "source/abi" }, WorkspaceMember { slug: "mstd", path: "source/mstd" }, WorkspaceMember { slug: "spitebuf", path: "source/spitebuf" }, WorkspaceMember { slug: "alloc", path: "source/alloc" }, WorkspaceMember { slug: "forth3", path: "source/forth3" }, WorkspaceMember { slug: "sermux", path: "source/sermux-proto" }, WorkspaceMember { slug: "trace", path: "source/trace-proto" }, WorkspaceMember { slug: "crowtty", path: "tools/crowtty" }, WorkspaceMember { slug: "dumbloader", path: "tools/dumbloader" }, WorkspaceMember { slug: "f3repl", path: "tools/f3repl" }, WorkspaceMember { slug: "allwinner-core", path: "platforms/allwinner-d1/core" }, WorkspaceMember { slug: "beepy", path: "platforms/beepy" }, WorkspaceMember { slug: "melpomene", path: "platforms/melpomene" }]) }), _schema: None }))'
↪ >o_o< INFO: Ok path
↪ >o_o< INFO: No config found, using default values
↪ >o_o< INFO: No config found, using default values
↪ >o_o< INFO: No config found, using default values
↪ >o_o< INFO: No config found, using default values
↪ >o_o< INFO: No config found, using default values
↪ >o_o< INFO: No config found, using default values
↪ >o_o< INFO: No config found, using default values
↪ >o_o< INFO: No config found, using default values
↪ >o_o< INFO: No config found, using default values
↪ >o_o< INFO: No config found, using default values
↪ >o_o< INFO: No config found, using default values
↪ >o_o< INFO: No config found, using default values
↪ >o_o< INFO: No config found, using default values
↪ >o_o< INFO: No config found, using default values
↪ >o_o< INFO: Found 57 paths to watch, starting watch...
⚠ >o_o< WARNING: Does exist!
⚠ >o_o< WARNING: Loading...
⚠ >o_o< WARNING: config => 'Ok(Some(OrandaLayer { project: None, build: None, marketing: None, styles: None, components: None, workspace: Some(WorkspaceLayer { name: Some("MnemOS"), members: Some([WorkspaceMember { slug: "kernel", path: "./source/kernel" }, WorkspaceMember { slug: "abi", path: "source/abi" }, WorkspaceMember { slug: "mstd", path: "source/mstd" }, WorkspaceMember { slug: "spitebuf", path: "source/spitebuf" }, WorkspaceMember { slug: "alloc", path: "source/alloc" }, WorkspaceMember { slug: "forth3", path: "source/forth3" }, WorkspaceMember { slug: "sermux", path: "source/sermux-proto" }, WorkspaceMember { slug: "trace", path: "source/trace-proto" }, WorkspaceMember { slug: "crowtty", path: "tools/crowtty" }, WorkspaceMember { slug: "dumbloader", path: "tools/dumbloader" }, WorkspaceMember { slug: "f3repl", path: "tools/f3repl" }, WorkspaceMember { slug: "allwinner-core", path: "platforms/allwinner-d1/core" }, WorkspaceMember { slug: "beepy", path: "platforms/beepy" }, WorkspaceMember { slug: "melpomene", path: "platforms/melpomene" }]) }), _schema: None }))'
↪ >o_o< INFO: Workspace detected, gathering info...
↪ >o_o< INFO: No config found, using default values
↪ >o_o< INFO: No config found, using default values
↪ >o_o< INFO: No config found, using default values
↪ >o_o< INFO: No config found, using default values
↪ >o_o< INFO: No config found, using default values
↪ >o_o< INFO: No config found, using default values
↪ >o_o< INFO: No config found, using default values
↪ >o_o< INFO: No config found, using default values
↪ >o_o< INFO: No config found, using default values
↪ >o_o< INFO: No config found, using default values
↪ >o_o< INFO: No config found, using default values
↪ >o_o< INFO: No config found, using default values
↪ >o_o< INFO: No config found, using default values
↪ >o_o< INFO: No config found, using default values
↪ >o_o< INFO: Building 14 workspace member(s)...
[kernel] ↪ >o_o< INFO: Building components: mdbook
[abi] ↪ >o_o< INFO: Building components: mdbook
[mstd] ↪ >o_o< INFO: Building components: mdbook
[spitebuf] ↪ >o_o< INFO: Building components: mdbook
[alloc] ↪ >o_o< INFO: Building components: mdbook
[forth3] ↪ >o_o< INFO: Building components: mdbook
[sermux] ↪ >o_o< INFO: Building components: mdbook
[trace] ↪ >o_o< INFO: Building components: mdbook
[crowtty] ↪ >o_o< INFO: Building components: mdbook
[dumbloader] ↪ >o_o< INFO: Building components: mdbook
[f3repl] ↪ >o_o< INFO: Building components: mdbook
[allwinner-core] ↪ >o_o< INFO: Building components: mdbook
[beepy] ↪ >o_o< INFO: Building components: mdbook
[melpomene] ↪ >o_o< INFO: Building components: mdbook
↪ >o_o< INFO: Building workspace index page...
✓ >o_o< SUCCESS: Your site builds are located in `public`.
✓ >o_o< SUCCESS: Your project is available at: http://127.0.0.1:7979
 WARN Ignoring Rust project, oranda is currently per-package and this looks like a whole workspace

One sort of weird thing is that ALL of the subprojects have detected the top level mdbook, and it gets rebuilt (and listed) on every subproject.

Screenshot 2023-07-24 at 20-19-02 MnemOS

Oh, actually it's also pulling in the README and the mdbook from the top level of the workspace:

Screenshot 2023-07-24 at 20-19-32 f3repl

I'm going to keep working to see if I can fix any of this through configuration, I'll edit the top post to hopefully avoid notification spam. Lemme know if you want to hop on chat anywhere to discuss.

Removing mdbook

Adding an actual README.md to the subprojects was enough to get rid of the "copied from top level" readme
To remove the top level mdbook, I needed to explicitly disable it (I dunno if the docs say this can be false, but the error when I made it null said data did not match any variant of untagged enum BoolOr at line 3 column 16, so I guessed and it seemed to work :) )

// source/forth3/oranda.json
{
  "components": {
    "mdbook": false
  }
}

Top level config

I sort of would like some top level information for my workspace project, I tried adding both a description and readme_path, but I can't make it include the readme.

{
  "workspace": {
    "name": "MnemOS",
    "description": "Hello this is mnemos",
    "readme_path": "./README.md",

(the page looks the same as above).

Grouping of Subprojects

So at least in mnemos, we have a couple "groupings" of subprojects, mainly: source/, which is a collection of crates, tools/, and platforms/. It would be nice to be able to do some customization on the top level page to group these somehow.

Ordering of subprojects

I also realized that subprojects are not ordered the same as they are listed in the oranda-workspace.json. They are not randomly ordered (like I would expect from a hashmap), nor are they alphabetical, nor are they the order in the workspace JSON.

Edit: I think they are alphabetical by crate name, not the slug name.

CSS/artifact caching

I noticed that building each project takes a second or two, which was really confusing to me. I tracked it down to the fact that for each subproject, oranda is making an HTTP request to get the (same) CSS (and something else?) over and over again. This happens in BOTH fetch_oranda() and fetch_css().

Until I noticed the slowness, I was not aware (and was surprised) that oranda would make http requests and "call home".

Asciinema:

ashleygwilliams commented 1 year ago

thank you so much @jamesmunns! this feedback is super appreciated! i'm sure @shadows-withal will look into this when they're in tomorrow. and no worries about notifications, so feel free to comment if editing the top gets too long

ashleygwilliams commented 1 year ago

one thing to note is that you are not getting the new styling for workspaces- so your index page looks a bit different than it should. i believe @shadows-withal is gonna cut a pre-release tomorrow so you won't have to do this but you can follow these steps to get the styles from main to build https://opensource.axo.dev/oranda/book/contributing.html#plus-working-on-the-css

jamesmunns commented 1 year ago

Thanks for the heads up @ashleygwilliams!

Probably done messing with things for today, it all generally works, enough that I would be happy to switch over our landing page as soon as the next release is cut (so I don't need to build from source in netlify's CI).

My WIP branch is here: https://github.com/tosc-rs/mnemos/pull/183, Feel free to clone and check it out if it's a useful test case.

There are a couple things listed above that I'd really love (particularly customizing the top level workspace page a bit - like ordering of subprojects, or including the top level readme), but none of those are blockers (as this is already an objective improvement from what we have now!).

Thanks again for building a very cool tool :)

shadows-withal commented 1 year ago

Hey! Thanks for taking this for a test drive, really appreciate it!

I just released v0.3.0-prerelease.1, which includes an up-to-date CSS build, so the index page should actually look correct: https://github.com/axodotdev/oranda/releases/tag/v0.3.0-prerelease.1

First, I got a little confused about whether oranda was using JSON or JSON5.

That's on me, I didn't even know there was a newer standard(?) of JSON that allowed comments. Will add a comment clarifying this!

I needed to go in and add more tracing output to finally get the error in Config::build_workspace_root(), because the ? on OrandaLayer::load(config_path)?; was swallowing the JSON error

Interesting, you'd think serde-json would catch this, I'll look into it.

One sort of weird thing is that ALL of the subprojects have detected the top level mdbook, and it gets rebuilt (and listed) on every subproject.

This definitely sounds like our autodetect is too greedy. We should probably tone it down a bit, I'll reproduce it with your test case and see if we can't make this behave Correctly without having to manually disable mdbook support.

Oh, actually it's also pulling in the README and the mdbook from the top level of the workspace

This one is interesting, as oranda shouldn't even work (in fact, it should error) if you don't have a local README file for your project, that's like the one thing it actually needs to function. How would you expect this to work for workspace members that don't have their own README but still are listed in the workspace configuration?

To remove the top level mdbook, I needed to explicitly disable it (I dunno if the docs say this can be false)

They don't, but this is something we should document, since it can be helpful in cases like this, where you need to bend oranda juuuuust a little bit.

Grouping of Subprojects

Interesting, this is something I hadn't considered yet... probably not something I can immediately implement, but it definitely makes sense, and I'll create a separate issue tracking it.

Ordering of subprojects

This is something I'll fix this week.

Including a top-level README is also something I'll focus on this week, that's definitely something I want to see in the next release that includes this feature!

If you want to chat about the implementation details or any other things you'd want to see, we can chat on Discord in the #oranda channel, if not, here is fine too :)

jamesmunns commented 1 year ago

I think the "inherit readme and mdbook" was actually a combination of things:

I added this to my workspace to try and get top level information:

{
  "workspace": {
    "name": "MnemOS",
    "description": "Hello this is mnemos",
    "readme_path": "./README.md",

And I think what happened is that all the subprojects "inherited" this.

jamesmunns commented 1 year ago

I think all of this has been superceded by other issues at this point, so I'll go ahead and close it!

axodotdev / oranda