Road to Release · Issue #60 · unisonweb/elm-browser · GitHub
Skip to content
This repository was archived by the owner on Oct 13, 2021. It is now read-only.
This repository was archived by the owner on Oct 13, 2021. It is now read-only.

Road to Release #60

Open
Open
Road to Release#60

Description

@nicklawls
nicklawls
opened on Nov 13, 2019

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.

Activity

  1. francisdb commented on Nov 13, 2019

    @francisdb
    francisdb
    on Nov 13, 2019

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

  2. nicklawls commented on Nov 17, 2019

    @nicklawls
    nicklawls
    on Nov 17, 2019
    CollaboratorAuthor

    Excellent suggestion @francisdb!

  3. nicklawls commented on Nov 17, 2019

    @nicklawls
    nicklawls
    on Nov 17, 2019
    CollaboratorAuthor

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

    #65

    Although handling builtin.Doc.Evaluate will be tricky!

  4. pchiusano commented on Dec 4, 2019

    @pchiusano
    pchiusano
    on Dec 4, 2019
    Member

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

  5. aryairani commented on Dec 5, 2019

    @aryairani
    aryairani
    on Dec 5, 2019
    Collaborator

    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!

  6. aryairani commented on Dec 5, 2019

    @aryairani
    aryairani
    on Dec 5, 2019
    Collaborator

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

  7. nicklawls commented on Dec 10, 2019

    @nicklawls
    nicklawls
    on Dec 10, 2019
    CollaboratorAuthor

    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.

  8. aryairani commented on Dec 10, 2019

    @aryairani
    aryairani
    on Dec 10, 2019
    Collaborator

    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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions