Add/Update project status in README #361
Comments
|
@e2 Thanks for your feedback. I will get back to this issue as fast as possible. |
|
@mattwynne @aslakhellesoy I think this is a good starting point for improving developer experience. Maybe we can even use this as a base for other sub-projects. |
|
@dg-ratiodata This guy really gets it: https://medium.com/the-javascript-collection/healthy-open-source-967fa8be7951#.lo0yohuij |
|
Thanks for sharing that post @e2 - I think the whole Cucumber ecosystem needs this |
|
@e2 Very good blog post. Thanks for sharing. |
That won't happen. Sorry.
RVM support is discontinued.
Created issues for a lot of wip things. Some more to come
Don't see the problem here. Personally I prefer "deprecations" first, then remove on major version release. If you fix your lib the deprecations are gone.
Yeah, that's really a problem.
There's a lot of documentation about how to do things right. Just head over to "features/".
Can you point me to the places where you found that stuff?
Do you talk about code coverage measure via
This will get better with
What about our API docs http://www.rubydoc.info/github/cucumber/aruba/master/frames? Do those help?
Having deprecations and then removable will not change.
Fixed
Yes, you're right. I hope we will get rid of those as fast as possible.
*, how to set in-process Aruba,
What abou this and this. And also added issued to track addition for documentation for rspec in #395.
I think this will become easier after removable of deprecated methods and the like.
It is and has more or less always been. PRs should be green before merged - see CONTRIBUTING.md
Besides the windows things which are tracked by issues, all tests should pass locally or at least should be ignore if a condition does not apply.
Mmmh. We're also using feature tests which are no reported "properly".
I think we're on a good way here.
Can you give me some more details what do you mean with this? Personally I won't give away information how busy I'm at work/free time. There's some meta information about the ongoings in the project via Github UI.
I think this is done in CONTRIBUTING.md now + the new templates for github issues/PRs.
I think with the new branch model. reporting makes sense.
What do you mean with that?
Milestones are used for that. |
In practice, every time Aruba is updated, new deprecations appear. There are so many of them, I'd prefer to just "start fresh" with an API without deprecations. Otherwise every minor release of Aruba is just a ton of new deprecations to debug - with not clear "upgrade notes" to just get it all done in one go. I'd rather just upgrade to 1.x and fix things once, and never look back. If I knew this was going to happen, I would've just locked to whatever version without deprecations and waited a few years for 1.x to appear. Otherwise, if the docs contain e.g.
That was months ago - I don't remember by no.
Mostly about RSpec files for every class and public method. Cucumber isn't good for testing edge cases.
No upgrade notes. I don't want to "re-learn" Aruba every single release every few months. Also, to documentation there is outdated (
By "crashed" I meant that I'd prefer to just switch to 1.x and redo things "the new way". Here, I don't have a 1.x version to switch to. Just a 0.x with tons of deprecations I have to hunt down and debug.
It's just to get a sense. If I'm busy working myself and I need something fixed in my project, I need to decide whether I can wait a few days to get a fixed merged and released ... or if I'm better off just forking, opening and issue and releasing my own gem. I don't mind waiting 5 years for my pull request to be considered, but I'd like to know beforehand if it's going to take more than a few weeks. I'm busy too - and I need to get stuff done. So either we can work together, or I still need to get stuff done.
If the answer isn't a straight "yes", then I'm assuming it's "no". If you're too busy and you don't want to accept maintainers or contributions ... that's weird. It doesn't make sense to carefully debug, fix and test issues just to make a PR to a dead project. E.g. RVM functionality is deprecated. But does it make sense to reject fixes if there's no 1.x? You can't drop it in 0.x, so you might as well fix it for now. You're either supporting old features due to a lack of a 1.x, or you're not supporting 0.x and you're releasing 1.x to fix that. Otherwise, it's effectively a dead project. And asking people to rebase after a few months is extremely discouraging. (You could've just pulled the changes before reorganizing the codebase). Right now, I feel like I just don't want to use Aruba anymore. I feel like testing things manually will take less time. I know how to program, so I don't need to go through volumes of "training wheels" or go scuba-diving to find what I need through the wreckage of deprecated methods. I'm strongly considering just using something like: https://github.com/abates/ruby_expect with RSpec instead. Or just running stuff in Docker.
The big question is: why hasn't 1.x been released for so long? Why is progress so slow? It's not that I want to hold anyone accountable, it's just so I can plan things on my side. "Working together" takes some commitment to availability on both side. I can't promise I'll still even be programming in Ruby 2 years from now, so if my issue/pull request is hanging out there for weeks, I might as well not make it. Especially if I post a bug fix and releases take months, there's almost no point in "sharing" my fix, because other people will still be hit by it weeks after my PR. Don't take it personally - I'm just already discouraged beyond salvation. I'm mentioning all this so maybe you can fix things before the next person becomes discouraged. (I know how it is not to get constructive feedback). |
That's not really useful for users because of all the "noise". If I update Aruba on an older project I get lots of deprecations. History.md doesn't really help me get through them. If a method is renamed, that's ok. If there' something bigger changed, I want to know how to do "X", especially if there's a new way to do that. Having tons of deprecations in a 0.x version is really weird and confusing. It's not that the API is changing that's bothering me, it's that changing my code just takes longer. As a user, I don't want to learn the internals of Aruba. I want to fix what's broken and focus on what's valuable to me and my clients. It's a bit like I have to "relearn" upon every minor update of Aruba, because I don't have a quick "cheat-sheet" of how to avoid deprecations and use whatever is recommended instead. Psychologically, during development, a deprecation is the same as a crash - it's hard to continue (it's an eyesore) with deprecations appearing. So really a NoMethod error with a backtrace helps "fix" deprecations much faster than browsing through a history file, or Aruba's source code.
It depends on the roadmap and bugfix support. In practice, major version upgrades are for removing deprecated functionality, really. It doesn't make sense to have 12 release for every minor in 0.x with a bugfix, so I understand that to get bugfixes it's best for me to rely on upgrading minor versions. So with Aruba, I'm upgrading minor versions to get bugfixes, mostly. (Because expecting them to be backported to older versions and released will be unlikely). The problem with upgrading minor versions is that I'm getting lots of deprecations that I don't even want to investigate. And deprecations are only for people stuck with an older version of Aruba. And without a 1.x, that's me - I'm stuck with ARuba 0.x with deprecations, and the next 0.x minor upgrade will probably have more deprecations. You also can't change the API once you get to 1.x. You can only "add" to the API and release bug fixes (as patch-level versions). You can only "change" the API in 2.x. If Aruba really wants to "decide on all deprecations up front", what it should have is a "tool" to convert my code to not be "deprecated". If it doesn't make sense - due to effort needed to create such a tool (which I understand) - I'd like to have a quick cheat-sheet of how to upgrade my API. I'm not a "dumb user" it's just that I don't want to waste time on something that's just a cost with no benefit. E.g. changing A "benefit" would be having some version (1.x? 2.x?) where It doesn't make sense for me to browse the whole Or, how am I supposed to know that examples for running something interactively are in: https://github.com/cucumber/aruba/blob/e880f1f7dfe384ef8ec7042fcce085ee17f208a5/features/steps/command/output.feature ? It's ironic, that the very thing I want Aruba to do (running commands, interacting with them while waiting for input/output, and debugging when things go wrong) are hidden either in the source code or in "enormous" feature files that are hard to skim through and hidden inside a feature tree under names that are hard to "guess" quickly. In short: releasing 1.x won't help me get my time back. Still better than "insufficiently documented" deprecations. If I'm going to get tons of deprecations in 1.x, I'd rather just wait for 2.x... I'm just not that interested in renaming API methods I call every few weeks. Things like that can really be put aside for 2.x, since new users are going to start with the latest version anyway. Probably the worst change is renaming announcer tags - and then I'm hacking Aruba's codebase wondering why debugging doesn't work... It's a bit like the only "benefit" Aruba is delivering right now are: deprecations and "better API method names". If I could "turn back time", I'd probably just write my own solution - because I'm not really interested in Windows or "doing everything in Cucumber" or "documentation in Cucumber" or anything other than Ruby-2.x, RSpec and Linux, really. I'm also unlikely to work on the same projects for 10 years, so if releases take months, I'll likely be gone by then. (I've already given up on using Aruba for a few projects already). I'd rather have a crappy (or bare-bones) 1.x with "quick-PR-review-and-release" cycles to make up for it. I really wish I knew earlier that Aruba is a bad match for me. I just want to "talk" with an app interactively, control it's environment and have test fail with understandable errors if something goes wrong. Ideally something I can easily copy and paste and use as a new project, without any setup. So it's not about "1.x" or "Semver" as much as: having an estimation of my costs vs my benefits. (And that goes both towards using Aruba as well as contributing). |
ghost
mentioned this issue
|
@e2 I tried to compile a list of this we can work based on from your comment.
Removal of deprecated code is now tracked here #396 .
What abou this? https://github.com/cucumber/aruba/blob/master/features/api/command/run.feature
That's tracked by #269 and unfortunately a known issue.
Have you seen https://github.com/cucumber/aruba#user-documentation? Would it help to have some documentation from the feature files rendered to HTML which is easier found by "Google" and the like? Maybe something similar to http://www.relishapp.com/cucumber/aruba/docs? Which was the first try to get documentation which is easier to access. Unfortunately it didn't work that well as you can see in the output.
That should have not happened. Sorry for that. You mean one of those? https://github.com/cucumber/aruba/blob/master/lib/aruba/cucumber/hooks.rb#L63
This is now tracked by #397 |
If I'm a Cucumber user, I only have ONE question: "what steps does Aruba provide?". Now, image Google search, except that without an input field you have all the possible categories of answers - and you had to find the answer you want by navigating the tree. Seems like a good idea from Google's perspective, but not too useful for users, right? Now, sure, there's this: http://www.relishapp.com/cucumber/aruba/v/0-11-0/docs/steps/overview-of-steps But, what I want is the RESULT of that command. It doesn't make sense for me to clone aruba and copy and paste that grep expression every time I need a reference of all the available steps. There are only 82 steps. 28 "Given", 22 "When" and 32 "Then". That's only 3 categories and about 20 entries each. That's not overwhelming for a cheatsheet. It's also a lot less intimidating than History.md. Meanwhile, I don't need 10 example scenarios of how to use The biggest flaw of Cucumber was: expecting business people to use it to create steps. I've seen project managers invent their own "version" of TDD, where one developers was supposed to write tests for another. At the end of the day, even software developers rarely get the steps right the first time, so there's rework. It's quite hard to create reusable steps that are just the right "size" and will survive unmodified across projects. And because steps are so prone to "updates", it's why memorizing them makes no sense. Which means an up-to-date "cheatsheet" is essential. With Aruba's current documentation, I have to pretty much extract such a cheet sheet on my own. And every release a few steps may be deprecated, so now in reality I'm a "documentation maintainer" if I want to be one or not.
This would be a much better README example than things like
Currently, Aruba seems to "favor" only succeeding scenarios. So it's favoring documentation (the easy part) over development (the hard part to get right). The problem is: no matter how beautiful the documentation is for successful scenarios, if you discourage developers by "hiding" useful tools and functions by default ... it's game over anyway, because they aren't going to want to use Aruba, except for documenting what already works.
I think Aruba has an identity crisis. It wants to present itself as a BDD tool, even though it's designed and prioritized as a "documentation tool". On top of that it technically has an API, although it's more like a DSL, and so Aruba is "embarassed" and thus tries to "hide" it's API. This means Aruba actually has 2 "interfaces": Cucumber steps and the "DSL". Take RSpec as an example - I have no idea what the internal classes are, and they're never mentioned in the docs. And I don't need them. E.g. I never need to explicity use config.around do |example|
foo.bar()
example.run
foo.baz()
endand that's exactly how it's documented: http://www.rubydoc.info/gems/rspec-core/RSpec/Core/Example It's called a "DSL" and not an "API". That's the distinction: So the term
Yes. Though the term "hooks" is misleading. They suggest there's something in the Aruba API that I can "hook into" for callbacks, etc. If you don't call them hooks in Cucumber, it doesn't make sense to call them something else when used for RSpec. Again, I don't have a RSpec cheatsheet for Aruba, so the best place is to look at Aruba's Cucumber steps. And there is no cheat sheet for those either. (Ideally, I'd just want to find the Cucumber steps I need, and then transplant them into my RSpec code - usually that's possible if the documentation has "source" links for steps and methods). Overall, I don't want to learn Aruba or dabble in it's internals just to fix deprecation warnings. I really expect to be able to quickly use Aruba just like I do with https://github.com/rspec/rspec-rails . Even if I don't use RSpec::Rails for ages, it's easy to find out how to use it with Rails 4 and RSpec 3, whether I'm writing routing specs or view specs or whatever. And that's all just from the README.md. Aruba is also confusing in where the project is at:
Overall, I'm biased in that I'm no longer an "Aruba beginner". What I remember is being utterly confused when what was supposed to be easy wasn't. I kept on finding out that I wanted to do something "obvious" and "typical" with Aruba, and I always ended up having to dive into the code to find answers quickly. For example: how do I wait for an interactive process to stop after typing in 'exit'? will Also, documentation navigation is a barrier. The most discouraging is to make 3 clicks just to get to a folder with only one file, then to go back up and "try another folder". So a cheatsheet would help a lot. (One that would be guaranteed not to be deprecated and won't require "generating" a list yourself). |
Summary
New contributors need a sense of "direction" to know what to expect when working on the current Aruba codebase.
Expected Behavior
Normally, when I want to contribute to a project I "expect":
Current Behavior
The biggest pain points I've had are:
Possible Solution
Again, general "info" about the project would help. Status, plans, ongoing work, etc. If I "step in" only to have to wait about a year for "other parts of the codebase to get sorted out first" - and then I find that over the year there's still no 1.x ... and while being spammed with deprecations that don't really tell me enough to know what's available (or at least hint why something was deprecated so I could intuitively "guess" what could work instead ... all this is a bit discouraging, even if there are valid/sound/understandable reasons behind everything going on.
The text was updated successfully, but these errors were encountered: