surf: convert to git-ref-format

FintanH commented 2 years ago

radicle-surf, historically, defined its own domain of reference types. This has, historically, caused some headaches for converting from surf types into radicle-link types. Now that git-ref-format is available to surf, we should plan out the conversion of the API to use those types instead.

[ ] Look at the current API and where it uses reference types
[ ] Plan out a migration path based on the above

Some things to consider:

Whether the input should always be Qualified, ie. have a category like refs/heads, refs/tags, refs/remotes
If we should do any newtype'ing to distinguish qualified refs, e.g. pub struct Tag(Qualified), with smart constructors
Are namespaces important anymore if we go down the protocol route of having a single repo per project? Thus, keep namespaces in the API but can de-prioritise the implementation of them

cloudhead commented 2 years ago

Good point about namespaces; we aren't using them in the new protocol!

keepsimple1 commented 1 year ago

When I was working on the PR, I was wondering what are the best examples of git-ref-format's benefits? I understand the points in its doc page, but it is not clear to me how much benefits it brings to overweigh the cost.

FintanH commented 1 year ago

When I was working on the PR, I was wondering what are the best examples of git-ref-format's benefits? I understand the points in its doc page, but it is not clear to me how much benefits it brings to overweigh the cost.

What are the costs you refer to here?

The benefits are:

It's a well-typed interface. It's useful to constrain your domain to well-known types, i.e. RefStr/RefString are valid references, Qualified is a valid reference that begins with refs/<category>, Namespaced is a valid reference that begins with refs/namespaces, and PatternString/PatternStr are valid refspecs. This is opposed to haphazardly passing around strings that we hope are correct. Another way of thinking about this is, "Parse, Don't Validate"
We use git-ref-format in important places such as git-storage, radicle-cob, and radicle. That means that those libraries will already passing around and returning types from git-ref-format.

keepsimple1 commented 1 year ago

Thanks. The costs I was referring to are fallible constructions of types in git-ref-format.

FintanH commented 1 year ago

Closed via #48

radicle-dev / radicle-git

surf: convert to git-ref-format #15