Giters

taskcluster / rust-hawk

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Expand README and other improvements

iddm opened this issue · comments

commented
  1. What version of the hawk the implementation conforms to?
  2. Add simple examples
  3. Add badges
  4. Add build bot support.
  5. Add a few examples.
  6. Add license information.
  7. Add explanation about future plans and what is currently implemented.
commented

Hi! This is mostly a learn-rust project for me, so you're welcome to work on these things if you are using the crate.

  1. To my knowledge, there are no "versions" of Hawk. There's just Hawk. And there's no "compliance", although the test suite does some basic interoperability checks against the main implementation (JS).

  2. Examples are in the docs

  3. Please feel free

  4. Buildbot? Why? Who would host it? That's hardly a README change :)

  5. See 2

  6. See LICENSE, although I'm happy to have that repeated in the README - feel free

  7. OK, fair enough :)

commented

I addressed point 7 with ed36f49.

I'm going to close this issue, but please do make a PR for anything you would like to improve!

commented
  1. There are versions :) Just above the table of contents :) It is said there that the current version is 7.
  2. Usually, people wanna see the docs only if they did not find the answer in the readme. This is the best thing to have, a short and the easiest and self-explained example right in the readme file. Just look at other crates, how they do this.
  3. I meant a CI-bot, not build bot :) So, it would be nice to have travis-ci support for this repository.
  4. We can see everything. We can even read the sources, so you can say there is no need in the README and docs at all. But people look at the readme at first, always. So for making people spending less of their time, it is usually the best practice to add a badge with license in the top of the README.

After all, as your crate is above the release (> 1.0.0 version) you must do that. The crate is used by people, there will be more people using it. Help them. Forget that this is your home-project in the case of README and the docs. I personally don't use it, but this is the only one implementation in the crates.io yet. Anyway, doing everything I told above is not that difficult but will help people much. Even if you say this is your learning project, if someone wanted to contribute, he would need to understand the project goals, documentation and the user experience at first. All of this could be done by providing good docs and the readme. I doubt anyone would contribute to a project which is just Cargo.toml with src directory.

I did not see any reason for closing this issue, however, do whatever you want :) It is up to you to help people :) No offence here.

commented

If you want these things done, your contributions are welcome.

Telling me what I must and must not do is not welcome.

commented

@djmitche Oh, I am sorry, you got me wrong. Excuse me for the "must" word :) I just wanted to help. My issue here is already a contribution because it gives some useful advices. If you don't wanna do anything - don't :) I just wanted to improve quality of the crate. There is a chance of me using this crate some time in the future and as your potential "client" I wanted to help you working on this crate by doing it better for both the clients and future contributors. Don't take it too seriously please. Probably you treated my issue as "you must do" right from the first comment here. Yes, I was wrong. I was so busy at work that did not even think that someone may get it wrong. Of course, everything in the list are nice-to-have things. Again, just wanted to help.

commented

Got it, thanks for explaining :)