If you guys feel strongly, I'm sure the Amazonica maintainers would love
a pull req that adds a small release script that handles this for them.
I'm sure it'd get merged, and it'd be a nice, constructive way to move
the discussion forward.
Gary Verhaegen <mailto:gary.verhae...@gmail.com>
November 20, 2014 at 7:58 PM
On Thursday, 20 November 2014, Michael Cohen <mcohe...@gmail.com
<javascript:_e(%7B%7D,'cvml','mcohe...@gmail.com');>> wrote:
No idea about the rest, but for the github part I usually expect a tag
for each release on Clojars, so if I want to read the actual code of
the release I'm using it is easy to find it.
This should have a very minimal impact on your workflow: it should be
limited to running git tag <version number> once right after each
release (or before; point is, if the unit of time is the git commit,
it should be simultaneous).
Note that it is possible that you have created these tags and they are
simply not on github because git does not push tags by default. You
have to run git push --tags to push them.
--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clojure@googlegroups.com
Note that posts from new members are moderated - please be patient
with your first post.
To unsubscribe from this group, send email to
clojure+unsubscr...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/clojure?hl=en
---
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To unsubscribe from this group and stop receiving emails from it, send
an email to clojure+unsubscr...@googlegroups.com
<mailto:clojure+unsubscr...@googlegroups.com>.
For more options, visit https://groups.google.com/d/optout.
Michael Cohen <mailto:mcohe...@gmail.com>
November 20, 2014 at 5:08 PM
Hi Greg,
I think all of your criticisms are very valid, and I think I've seen
most of them voiced by others at various times. I wrote it in about 3
weeks in March of 2013, when I was very new to Clojure, so I'm sure I
made lots of mistakes. I was using some Java with AWS and some
Clojure, with James Weaver's rotary library, and when you look at the
Javadocs, it almost seems like the Java SDK could be generated. So
that leads one to think....and off I went.
As far as the problem areas you identified:
- shitty docs
What can I say, guilty as charged. Sorry. I tried to do a decent job
with the examples, although I laughed when I heard Stu Halloway slag
off "documentation by example" in some tech talk. Oops. What else
could I do? I looked at trying to generate some more codox type docs
from the Java SDK, but I just wasn't going to endure that pain. So,
yeah, I hear you. It's a trade off though. I'm sure there's a few
folks out there that would have to use Java interop and the Java SDK
(and pour through those same Javadocs) in order to use one of the less
popular AWS services if Amazonica didn't exist, because nothing else
would exist in the Clojure world for that particular AWS service. Man,
when I wrote this I don't even think there was a decent Clojure lib
for ec2.
- dynamically generated api
Yeah, the code is not as straightforward and reflection is expensive.
The counterpoint to that I guess would be, once you have it well
sorted, you don't really need to edit core.clj too much. And with most
of the AWS api, the cost of reflection is negligible compared to the
network hop. You're also probably not that concerned with latency at
all for those use cases. But again, it's a trade off. Buy one get 20
was worth a little reflection to me.
- Functions are both variadic and dispatch on argument type
Again, guilty as charged. I would do things differently today.
- There are no releases or tags on github
Again, I didn't really know what I was doing here, and never really
changed the approach. What do people expect, a snapshot release for
current development, and periodic version bumps and releases (less
frequently than Amazonica currently bumps the version numer)?
Mike
Greg Mitchell <mailto:metroidphr...@gmail.com>
November 20, 2014 at 1:32 PM
Thanks for creating this library, Michael. Your solutions for writing
the library are creative for sure, and this library has helped with
developing with AWS. However, I've been using the amazonica library to
communicate with AWS components in an enterprise-scale project for
about a year now, and I've come to believe that some of the design
choices in the library and its maintenance are big anti-patterns. All
of these are things I've struggled with in developing against Amazonica:
* The documentation is sparse and the code is not self-documenting.
Clojure in general tends to have worse and less documentation than
Java. This is usually mitigated in well-designed Clojure libraries by
being able to break into the source and read short, comprehensible
functions with descriptive names. Amazonica is in the worst of both
worlds by having no documentation in source, sparse documentation on
github, and using dynamically generated code. Specific improvements to
documentation I'd love to see: a comprehensive list of keys that
credential maps and functions take as well as their valid values. The
one or two examples per API on Github are insufficient for different
combinations of functionality in real-world use cases. Pointing to AWS
javadoc is not sufficient because Amazonica does name-munging and
unwrapping - in order to understand the Amazonica input/output, you
have to be an expert with the library and look at the implementation
for name-munging. It is effectively a new API. A comprehensive list of
functions would be nice, but finding them at the repl is a reasonable
work around.
* Dynamically generating an API doesn't save anyone time
This is an extension of the previous point. You have almost 800 lines
of code, mostly dedicated to reflection and interning methods. It's
impressive that the whole thing works as well as it does, but doesn't
actually save time vs. explicitly targeting an API with small wrapper
functions. That has the benefit of being very obvious and easy to
understand (as described above). It does mean you have to do some work
when the Java SDK changes or you add a client, but I see there is
already some nasty logic to switch on the client class if it has a
different interface. There's a performance cost in reflection too.
* Functions are both variadic and dispatch on argument type
Especially without clear javadoc style documentation for function
arguments, types, and keys, having functions that take a smorgasborg
of different arguments is incredibly confusing. I think the root of
this problem is the choice to make the client methods variadic,
because then there can't be well-specified arities for the various
cases (no credentials or arguments, credential map, just arguments,
credential map and arguments), using repl. If the functions instead
had 0, 1, and 2 arities that took nothing, an argument map, or a
credential map and an argument map, it would be so much clearer. Also
argument maps are generally a little easier to work with than
destructuring the rest.
* There are no releases or tags on github
My company has a tedious process for importing third-party packages
into source control. It's not ideal, but I'm sure it's not unique. It
would be great to be able to pull in a stable release built against
well-specified versions of dependencies.
I hope this doesn't come across as harsh, that's not my intent. I
really do appreciate you writing this library, and I realize that
given how mature it is, completely changing the implementation is
probably unfeasible. I just want to raise these concerns and see
whether other people share them. If so, maybe they can serve as
patterns or anti-patterns for future libraries.
-Greg Mitchell
On Monday, March 25, 2013 2:51:42 PM UTC-7, Michael Cohen wrote:
--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clojure@googlegroups.com
Note that posts from new members are moderated - please be patient
with your first post.
To unsubscribe from this group, send email to
clojure+unsubscr...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/clojure?hl=en
---
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To unsubscribe from this group and stop receiving emails from it, send
an email to clojure+unsubscr...@googlegroups.com
<mailto:clojure+unsubscr...@googlegroups.com>.
For more options, visit https://groups.google.com/d/optout.
--
Sam Ritchie (@sritchie)
Paddleguru Co-Founder
703.863.8561
www.paddleguru.com <http://www.paddleguru.com/>
Twitter <http://twitter.com/paddleguru>// Facebook
<http://facebook.com/paddleguru>
--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clojure@googlegroups.com
Note that posts from new members are moderated - please be patient with your
first post.
To unsubscribe from this group, send email to
clojure+unsubscr...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/clojure?hl=en
---
You received this message because you are subscribed to the Google Groups "Clojure" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
