-
Notifications
You must be signed in to change notification settings - Fork 23
Update according to Contributors library guidelines #53
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Update according to Contributors library guidelines #53
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
README.md
Outdated
@@ -1,148 +1,43 @@ | |||
# purescript-uri | |||
# uri |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
That should be better documented. The short version:
display-title
is used only in headers, when you might display the package in title case. Defaults to the package name, no backticks.display-name
is 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.
backups/README.md
Outdated
|
||
``` | ||
bower install purescript-uri | ||
``` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This file can be deleted.
docs/README.md
Outdated
@@ -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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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. |
This pull request is part of an effort to update and standardize the Contributors libraries according to the Library Guidelines. Specifically, it:
test
directory.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.