-
Notifications
You must be signed in to change notification settings - Fork 98
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
Cleanup up READMEs #359
Cleanup up READMEs #359
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.
While the link should be updated for cargo fmt
, we need to maintain a mention of using cargo +nightly fmt
as that's what CI tests or change CI to not use nightly
.
(Right now, there's no difference between the two.)
@waywardmonkeys I'm honestly not too concerned. I'm more worried about getting PRs at all than hoping people read a bunch of guidelines and use the right version of a formatter. CI will catch it if they don't (and there happens to be any difference at the time) and at that point I can even tweak commits if need be. I thought of starting a CONTRIBUTING.md or similar with some guidelines for things like that we won't accept major performance regressions and how to benchmark, but am still trying to get my head around all the pieces. We have so little contributor flow I'm not in a hurry for that. In the mean time I just too a stab at redoing all the crate summaries with relevant info. Any thoughts on if I got the gist of that right? |
314971f
to
be4430e
Compare
Does anybody know the maximum (displayed, not necessarily allowed but truncated) length of crate descriptions on crates.io? I set this up with all crates having a one liner about Project Fluent and a one liner about the specifics of how the crate fits in the bigger picture. My concern is that's going to be too long to be published, or if published might be truncated in many places where it would be useful to see. I'd like to rewrite them to at least reverse the order and maybe more concisely summarize the Project Fluent part, but I don't how what my target length should be. Anybody know? Edit: c.f. rust-lang/crates.io#8739 |
…ted search results
I think I'd like to leave this PR here before the scope creeps farther. There is lots more to do but doing to much at once I think will make it hard to review. The next step is probably to work on the crate docstrings at the top of each lib. There is quite a lot of overlap and crate conflation in those docs too, as well al overlap with the READMEs. In fact what I will probably work towards is getting the crate summaries, usage blocks, examples, etc. all moved to the READMEs, then including the readme automatically in the package docs and eliminating the content from the code files. |
One of the first things that bothered me about the Fluent project was how confusing it was to figure out what crates to even start with. A major factor in that is that all the README's for the crates in this project have a bunch of generic content and it isn't clear which bits are crate-specific.
The goal with this PR will be to sort out what introductory "Project Fluent" docs should go everywhere, vs. how each crate is described, vs. how all the other crates are cross-linked.