opened
gonzalo-bulnes
username_0
Hello,

I decided to tackle https://github.com/username_0/dredd-rack/issues/7, and to implement it using this gem in order to keep concerns separated. Before making _dredd-hooks-ruby_ a dependency of Dredd::Rack, however, I'd like to refactor/improve it a bit so:

- its versions are named following the [Semantic Versioning][semver] conventions
- it has a change log ([example][changelog])
- its code "feels more like Ruby" - follows the usual naming conventions, is a bit more idiomatic...
- its maintenance is easier for a Ruby dev. - add a few Rake tasks for testing, eventually add a unit test suite

I'm happy to do that as a contribution to _dredd-hooks-ruby_, and opened this issue for coordination purpose.

**More details**

Some of that will be refactoring, but some will also introduce changes  in the API (following the naming conventions may change the `include DreddHooks::Methods` statement for example), but to make it more familiar to Ruby developers.

What I see as the API:

- the binary name, and default URL, ports [can't be changed because Dredd relies on them]
- the DSL [I see no reason to change it]
- the DSL inclusion statement [if I change it I'll make the change explicit - that's the point of semantic versioning]
- the hook names [no reason to change them, I mean it's a Dredd concern not a _dredd-hooks-ruby_ one] 

**Questions / Ideas**

I've forked the project, and will start working on it. I have a few questions:

1. I could formalize my TO DO list as a series of issues here (I can't open them against my fork), and close them from the corresponding commits. IMO it would allow to set a roadmap and they could be tagged accordingly, but I want to be sure it's OK before flooding you with issues and PR
1. I'm assuming the current version being **0.0.1** makes changing the versioning scheme and slightly modifying the API not a big deal, but again, you are the maintainers and I don't want these changes to sound scary
1. Finally, I think I can PR/merge against my own fork for a while, but I'd prefer to be able to increase the `0.x.x` version number to reflect the changes and Travis won't help if the corresponding releases are not available - that's mainly why I would prefer to PR here. Another option would be that I release those as `dredd-hooks` (instead of `dredd_hooks`) then handle it to you at some point (I think it would be a better name anyway, but let's explain that in the corresponding PR).

What do you think?

  [semver]: http://semver.org
  [changelog]: https://github.com/username_0/simple_token_authentication/blob/master/CHANGELOG.md
Coordination
issue
created
gonzalo-bulnes
username_0
That's for the first step, a general review of style and tools. I haven't started renaming or DRYing anything yet.

The second step will be renaming things and removing duplication in a backward-compatible way, and I'll propose a few non-backward compatible changes as a third step.
comment
created
honzajavorek
username_1
Exactly. I think in this case the version 0.0.1 basically denotes "initial implementation".
comment
created
gonzalo-bulnes
username_0
Hi @username_1,

Thanks for your details answer and for the green light! :D 

I'll put together a summary of the changes I already made and post it here in the next few days. I'll also open a few issues to reflect the refactoring I've done so far and the few changes to come.

Note that I'm commenting each commit to ensure you can follow the refactoring even if not that familiar with Ruby, and commenting my intentions in each of the PR I opened against my fork. Anyway, I'll let you know when introducing more substantial changes, so you get a chance to step in.

**Schedule**

I started yesterday doing some preliminary refactoring before DRYing the `DreddHooks::Methods` and `DreddHooks::Runner` ([work in progress][dry-dsl]). I'll discuss the changes I made in the [corresponding PR against my fork][dry-dsl] to set some context and allow anyone to step into the discussion when they're ready.

In the next few days I plan to start DRYing these two modules quite a lot, in order to make the DSL extension as simple and cheap as possible.
Then I'll modularize a little bit the `DreddHooks::Server` for readability and rename a few things around (in a backward-compatible way).

That's going to take some time, and by then we should be able to discuss about the third step I mentioned earlier. : )

  [dry-dsl]: https://github.com/username_0/dredd-hooks-ruby/pull/6

**About the change log**

I took a quick look at the references you mentioned and I think I got the idea. I'll start adding a few missing elements on the [`CHANGELOG`][changelog] I added to get it closed to the other ones, and, again, we can talk about it at some point.

Cheers!

  [changelog]: https://github.com/username_0/dredd-hooks-ruby/blob/29cd583e4fd336bf1f7591c3d007e17929a3efea/CHANGELOG.md
comment
created
gonzalo-bulnes
username_0
Hi @username_1,

_I made a mistake an committed the entire refactoring with the wrong identity. It's fixed now, and_ I'm recreating the pull requests against my fork so you can review them when you're ready.

Also I think it's simpler if I create **one single** PR for the first step (refactoring to make the project more idiomatic and DRYing the code). It will correspond to the first ten PR against my fork.

Then **one single** PR for the backward-compatible renaming tasks. And finally **one single** PR for the non-backward-compatible (but sensible IMHO) renaming tasks.

The three PR will reflect the different levels of "discussability" and reducing the review/discussion/merge process to three steps should make it less time-consuming for you as a team. What do you think?
comment
created
honzajavorek
username_1
@username_0 Sorry for not being responsive for a while. I'll try to get someone skilled in Ruby :gem:  fast to review your work (I'm convinced it'll be awesome!). If everything goes well and if you don't mind, I'd consider to add you as a contributor to the repository, so the changes are easier to coordinate. You do a lot of very good work here and I feel my lack of dedication to `dredd-hooks-ruby` only slows you down in making the project better.
comment
created
gonzalo-bulnes
username_0
Hi @username_1,

Please don't worry about timings, you all do an awesome job creating all these tools and sometimes slowing down a little bit gives the occasion to make better decisions : )
Hopefully, the maintenance tasks [should become easier with the recent refactorings][doc].

I'd be glad to get contributor access to the repo, thanks for your trust!

I'm currently writing a small example application so I can check that I'm not missing anything important to make the `DreddHooks::Server` usable as a library.

  [doc]: https://github.com/username_0/dredd-hooks-ruby/blob/refactor-ensure-server-can-be-used-as-library/doc/README.md

I'll keep you updated!
comment
closed
gonzalo-bulnes
username_0
issue
created
gonzalo-bulnes
username_0
I'll close this issue since coordination is now ensured in #13 : )
comment
reopened
gonzalo-bulnes
username_0
Hello,

I decided to tackle https://github.com/username_0/dredd-rack/issues/7, and to implement it using this gem in order to keep concerns separated. Before making _dredd-hooks-ruby_ a dependency of Dredd::Rack, however, I'd like to refactor/improve it a bit so:

- its versions are named following the [Semantic Versioning][semver] conventions
- it has a change log ([example][changelog])
- its code "feels more like Ruby" - follows the usual naming conventions, is a bit more idiomatic, a bit DRYer...
- its maintenance is easier for a Ruby dev. - add a few Rake tasks for testing, eventually add a unit test suite

I'm happy to do that as a contribution to _dredd-hooks-ruby_, and opened this issue for coordination purpose.

**More details**

Some of that will be refactoring, but some will also introduce changes  in the API (following the naming conventions may change the `include DreddHooks::Methods` statement for example), but to make it more familiar to Ruby developers.

What I see as the API:

- the binary name, and default URL, ports [can't be changed because Dredd relies on them - correct me if I'm wrong]
- the DSL [I see no reason to change it]
- the DSL inclusion statement [if I change it I'll make the change explicit - that's the point of semantic versioning]
- the hook names [no reason to change them, I mean it's a Dredd concern not a _dredd-hooks-ruby_ one] 

**Questions / Ideas**

I've forked the project, and will start working on it. I have a few questions:

1. I could formalize my TO DO list as a series of issues here (I can't open them against my fork), and close them from the corresponding commits. IMO it would allow to set a roadmap and they could be tagged accordingly or assigned to myself, but I want to be sure it's OK before flooding you with issues and PR
1. I'm assuming the current version being **0.0.1** makes changing the versioning scheme and slightly modifying the API not a big deal, but again, you are the maintainers and I don't want these changes to sound scary

What do you think?

  [semver]: http://semver.org
  [changelog]: https://github.com/username_0/simple_token_authentication/blob/master/CHANGELOG.md
  
**Edit**: I removed the third question because I was mistaken: Travis CI is installing the gem locally, and there is no inconvenient in bumping the version number without releasing the corresponding gem. I'll just start working in my fork, and am willing to PR the result as soon as you want. : )
Coordination - ensuring the gem is production-ready
issue
created
gonzalo-bulnes
username_0
Given its title, maybe I should keep this issue open until **v1.0.0**. Sorry for the confusion.
comment
created
gonzalo-bulnes
username_0
@username_1 @netmilk I released **v0.1.0**, as a Semantic Versioning starting point.

No breaking changes from **v0.0.1**, and no new features either ([`CHANGELOG`][changelog]). In particular I didn't start adding documentation to the CLI itself, just to be sure not to put too much in a single release.

Now I'll start using Dredd Hooks in Dredd::Rack to properly check that the `DreddHooks::Server` can be used smoothly as a library (I don't expect big problems, but I still expect to highlight minor issues). From there I'll determine the next steps to fix any remaining issue and improve the user experience. If you have any comments, ideas, just let me know : )

  [changelog]: https://github.com/apiaryio/dredd-hooks-ruby/blob/v0.1.0/CHANGELOG.md
comment
created
honzajavorek
username_1
@username_0 AFAIK sem ver doesn't support anything below v1.0.0 and recommends to start versioning with v1.0.0, but I didn't check this against the spec.

👍 to all the work you did, it's really outstanding!
comment
created
gonzalo-bulnes
username_0
While the recommended version constraints must be as strict as possible at that point (currently `'0.1.0'` in our case, that means no one depending on the Dredd Hooks gem will see it updated without explicitely updating the constraint in their `Gemfile`), I still see value in setting milestones towards stabilizing the API.
Primarily, it allows to establish early communication with potential users and prevent uncomfortable elements to become part of the API.

I also found that the semver convention can easily be extended to make the communication a bit more expressive, and in my pre-1.0.0 projects I enforce the following addition:

As long as MAJOR is 0:
- PATCH releases SHOULD NOT (but MIGHT) introduce non-backward-compatible changes to the current API
- MINOR releases MAY introduce non-backward-compatible changes or not, but SHOULD display a visible warning in their `README` when they do. (It MAY happen, though, that such changes be released without warning, see semver.org)

That is optional (of course), fully compatible with the semver spec and any user ignoring this and referring to the spec would err on the safe side (assuming that anything can change anytime).
Even if not used explicitely, however, I find it provides a good guideline for communication and forces me to think early about what the project API is, while allowing changes (and mistakes!)

That what I had in mind when saying "a semver starting point" : )

**Note**: Indeed, I never used this explicitely so far - I don't think it would help users to know the details, and the improvement in the communication should be perceptible without needing to agree on one more spec.
comment
created
honzajavorek
username_1
@username_0 Okay! I totally dig moving towards sem ver 👍 I probably got just confused with the 0.x.x versions. As you write, it is valid sem ver, but [sem rel](https://github.com/semantic-release/semantic-release) had problems with it, so I probably just made an incorrect connection in my brain between those two.
comment
created
gonzalo-bulnes
username_0
I think you cannot really automate anything before v1.0.0, right? That's probably why. (I'm not familiar with Semantic Release, but I saw the Dredd issue about it; it reads interesting.)
comment