Update according to Contributors library guidelines - #53
Conversation
thomashoneyman
left a comment
thomashoneyman
left a comment
There was a problem hiding this comment.
This is pretty good! I think we can remove the backups directory and I'd like to switch 'uri' for 'URI' in the titles and purescript-uri for uri as the displayed package name.
| @@ -1,148 +1,43 @@ | |||
| # purescript-uri | |||
| # uri | |||
There was a problem hiding this comment.
I'm in favor of capitalizing packages in titles where appropriate (in this case, URI). In the tool that'd be --display-title URI.
There was a problem hiding this comment.
Ok. I'm going to run the following code to update this:
contrib-updater generate --title 'URI' --maintainer garyb --display-name '`uri`'
It wasn't clear to me what the difference between title and display-name was, nor our preference for how to use each.
There was a problem hiding this comment.
That should be better documented. The short version:
display-titleis used only in headers, when you might display the package in title case. Defaults to the package name, no backticks.display-nameis used when referring to the package informally, like "Thank you for contributing to ". Defaults to the package name, with backticks (so specifying--display-name '`uri`'is not necessary)
The package name itself is used in any installation / code instructions (but this is done automatically for you, with no option). Typically I'm only supplying the --display-title flag to capitalize the package and rely on the package name for the display name.
|
|
||
| ``` | ||
| bower install purescript-uri | ||
| ``` |
There was a problem hiding this comment.
This file can be deleted.
| @@ -0,0 +1,134 @@ | |||
| # uri Documentation | |||
|
|
|||
| This directory contains documentation for `purescript-uri`. If you are interested in contributing new documentation, please read the [contributor guidelines](../.github/CONTRIBUTING.md) and [What Nobody Tells You About Documentation](https://documentation.divio.com) for help getting started. | |||
There was a problem hiding this comment.
Another place to rename the package name to just uri.
| Along with these types, you'll want to define an options record that specifies how to parse and print URIs that look like this: | ||
|
|
||
| ``` purescript | ||
| options ∷ Record (URIRefOptions UserInfo (HostPortPair Host Port) Path HierPath RelPath Query Fragment) |
There was a problem hiding this comment.
This hasn't been mentioned before, but I would like to standardize on no unicode symbols within contrib. I think they're perfectly fine in personal code, but it certainly seems standard in the community to use non-unicode characters (:: instead of ∷ here) and it means cotributors who don't use them don't have to learn how to create or copy-paste them. If you have a moment to glance through and replace them in the docs I think that would be useful.
There was a problem hiding this comment.
I think every place you would expect ::, Gary used ∷. I think I prefer the unicode character because things line up better and forall is reduced to something much smaller. However, I realize that could confuse new people who aren't sure what that means.
Regardless, I think we should address this in a separate PR.
|
I've addressed your comments. |
2 participants
This pull request is part of an effort to update and standardize the Contributors libraries according to the Library Guidelines. Specifically, it:
testdirectory.This PR is the groundwork for followup efforts to ensure contributor libraries are kept up-to-date, documented, tested, and accessible to users and new contributors.