UX

[dgreisen]

need to improve the cli ergonomics. Current ideas/plan:

• require a .stele folder in the library root.
• stele can do whatever it needs to in that .stele folder - configs, default logs location, sqlite, etc
• specify an optional library path --library-path for any command.
• if you call stele without specifying a library path, it will look up the dir tree to find a .stele folder and use that as the library path.
• If it is unable to find a .stele dir, it will error.
• commands:
  • serve
  • clone
  • update
  • validate
  • init-library

@renatav @n-dusan @tombh: thoughts?

[tombh]

Sounds fine. My immediate thoughts (which have nothing to do with Rust) are;

• It's not clear why the .stele folder can't be created if it doesn't exist
• It sounds more like --data-path than --library-path. I have no intuition for --library-path
• Personally I would naturally expect the option on the main command rather than on the subcommands, eg: stele --libarary-path .stele serve

Edit: ohh, it depends on the bare Git repo! In which case, I don't think this an option then, it's an arg: stele <path to bare git repo of OLL law> subcommands

[renatav]

@tombh The concepts of library and library path are are used throughout our platform, it's something specific to our project, so I think that we should keep that name. A library = our digital law library.

@dgreisen in taf clone and update are basically the, updater will clone the repos if they don't exist, update them if they do. We can create wrappers around the commands so that clone raises an error or does not do anything if the repos exist if that makes sense

[n-dusan]

So my understanding is that we are porting some of taf features to stele? @renatav If I remember correctly, I recall our conversation about separating out cloning from taf update, and I think it was because of UI/UX purposes. I do agree that it would be more ergonomic to have a clone command separately, since it won't be called as much as update.

[dgreisen]

@tombh - A Stele library has a particular layout:

- $LIBRARY
  - /.stele     # <- proposed
  - /<namespace1>
    - /law
    - /law-xml
    - /law-html
    - /law-...
  - /<namespace2>
    - /law
    - /law-xml
    - /law-html
    - /law-...

where the namespace usually corresponds to the github org.

We don't want to create a .stele directory for the same reason we wouldn't want to create a .git directory when someone does git log we wouldn't know what folder to put it in, or if they even meant to run the command in a folder that wasn't a git working dir.

Instead, we use the .stele folder to let us know that we are in a stele library. If we are in a stele library, then we can be confident the person meant to run the stele command on this stele library.

@renatav - I agree with @n-dusan that we should split clone and update for ergonomic reasons.

@n-dusan - While working on the grant, we talked about renaming TAF to Stele. I thought everybody liked that idea, but let's discuss, if that wasn't agreed to by everybody. The ultimate goal would be to move/rename all of TAF into Stele. I have definitely found it confusing to talk about TAF vs TUF.

[dgreisen]

Edit: ohh, it depends on the bare Git repo! In which case, I don't think this an option then, it's an arg: stele subcommands

it actually doesn't depend on the bare repo, it just depends on the repos being in a certain location relative to the library root so it can find them. That's why we must have the library root. But, I was thinking that, just like with GIT, if you are inside of $LIBRARY root, then you shouldn't need to specify the path to library, since we can just look up the ancestors to find the root.

[renatav]

@n-dusan @dgreisen I remember the requirement to create a separate clone command and it make sense, just like how git has clone and pull. I'm just saying that I'd prefer that to be a wrapper around the updater than to directly implement in the updater, since the updater is consistent with TUF's referential implementation. We can even rename update to pull if that would make more sense. I like the idea of a .stele folder, it's nicer than keeping our config files directly inside the library

[tombh]

Thanks for the replies, it's making more sense now.

@renatav Being new to all this (and hopefully there'll always be a constant stream of newcomers as OLL slowly becomes the de facto saviour of civilised society in the decades to come haha), "library" has other meanings in my mind, particularly software libraries, like libc etc. Maybe oll-library is too clumsy. But anyway, either way I'm just sharing my newbie perspective, in case it's useful.

@dgreisen So what are the differences that prevent the CLI UI being exactly like Git's?

[dgreisen]

@tombh - mostly that git's ux is terrible :D. I think we'll want to make it much simpler than git.

we have a bunch of unfortunately overloaded terms between legal nomenclature, library nomenclature and programming nomenclature. The worst, perhaps, is code, followed closely by repository. I don't think there is a way to avoid it without choosing to go completely to the software side and give up on lawyers and librarians.

I've implemented library detection. Git server is now started by running stele git, while stele serve is reserved for starting the real publish server when that is implemented. I'm going to close this

[tombh]

Oof yeah the associations with "code" and "repository" are strong too.

Ok, that's great that you're already so productive in Rust 😏