Road to Release - Githubissues

nicklawls commented 4 years ago

Reading this in the last Unison blog post got me all jazzed up:

The idea is that you can hyperlink to any Unison definition, in any Git repo, and render that definition nicely with hyperlinks to all its dependencies. And rather than this being a build artifact that every library author must maintain and keep up to date, it's something that Just Works for all publicly hosted Unison code, without any action needed by library authors! It works by reading the underlying codebase format which has all the semantic information needed for this to be possible.

That said, having peeked back into the code here for the past few days, I'm unclear as to how far towards that goal everything is. I wanna ask some general questions here, and hopefully generate enough discussion to write up issues that will get this baby shippable.

Do we know what the URL format will be? www.unisonweb.org/browse/<git-stuff>/<hash>? Lots of options
How will the server handle all the git data it'll be dealing with from across the internet? Just pull the files over the network a-la-carte? Clone a whole repo the first time it sees it? (Edit: it looks like there's actually some preliminary elm code for getting files from GitHub. I suppose we could do it client side as well)
How much tweaking does the UI need? The current trajectory seems to be towards something very much like the elm-package site, with the currently focused namespace in the main content area, and a filterable list of sibling namespaces off to the right (example). But of course for each type and term definition we should display hyperlinked source code, in addition to any linked docs and tests
Are "Branch"es a user facing thing? It seems to me that maybe "namespaces" or "paths" are the user-facing abstractions that are implemented by branches under the covers.
Perhaps related to the above, do we really want the little predecessors/parents/successors control at the top of the page? It seems to be going through history somehow, but it's doing it in a way that changes what gets rendered in the right sidebar. Not sure how to interpret all that.
How much provenance of definitions should we show? Say my library depends on some well known/trusted library called 'foobar', which I, following its readme instructions, installed via pull https://github.com/foobar-author/foobar .foobar in the ucm shell. Wouldn't it be nice for users of my code to see that everything from .foobar is the same set of well-known code they're used to seeing? The names alone aren't enough to tell you that.

francisdb commented 4 years ago

You might want to ask these questions in one of the unison slack channels https://www.unisonweb.org/community

nicklawls commented 4 years ago

Excellent suggestion @francisdb!

nicklawls commented 4 years ago

Made a separate issue to start tracking Docs rendering, which seems like some good low-hanging fruit

https://github.com/unisonweb/elm-browser/issues/65

Although handling builtin.Doc.Evaluate will be tricky!

pchiusano commented 4 years ago

Notes from discussion:

Going to focus on just having a viewer of individual definitions, which has very few unknowns and is also incredibly useful.

Some bikeshedding on URL format that we were just whiteboarding:

www.unisonweb.org/browse/(github|gitlab)/xilnocas/myunisoncode/latest/by-name/path/to/mydefinition
www.unisonweb.org/browse/(github|gitlab)/xilnocas/myunisoncode/<namespacehash>/by-name/path/to/mydefinition
www.unisonweb.org/browse/(github|gitlab)/xilnocas/myunisoncode/<namespacehash>/by-name/path/to/mydefinition
www.unisonweb.org/browse/(github|gitlab)/xilnocas/myunisoncode/<namespacehash>/by-hash/<hash>

If there's multiple things with a name, just show them all.
If there's nothing with that name, friendly message (maybe even spell correct to suggest "nearby" names that are valid)

Doc Evaluate nodes can just be rendered as links to the source of the definition being evaluated with some subtle indicator + tooltip about how the user can evaluate the definition locally.

Idea: Maybe the view page for a definition gives the UCM instructions for fetching that definition at the bottom. ("How do I get this definition?")

aryairani commented 4 years ago

We should use a URL format that supports git branches and git hashes and supports looking up definitions named /.

I recommend checking UriParser.hs for inspiration!

aryairani commented 4 years ago

Something like this should also work: https://github.com/unisonweb/unison/blob/c8e7f002a2d8858cdd961bbaa300ebc55318ee95/parser-typechecker/src/Unison/Codebase/Editor/UriParser.hs#L26-L55

nicklawls commented 4 years ago

I took a first crack at URLs based on @pchiusano's comment from last week.... didn't notice @aryairani's additions till afterward 😅

I can report that elm/url's parser API wouldn't let me parse arbitrary length paths (.../path/to/mydefinition), so I needed to resort to .path.to.mydefinition anyway. That pushes things pretty darn close to the format outlined in the link above, so maybe we should just go the rest of the way there for ecosystem consistency.

aryairani commented 4 years ago

It supports branch names, which are hard to parse without IO that literally checks for the existence of such a branch, because they can include ., /; everything but :, basically. :-\

And... I couldn't bring myself to not support git branches, given what a fundamental part of git they are.

unisonweb / elm-browser

Road to Release #60