Regarding releases, the lein release function gives you good defaults for releasing Clojure projects, it handles tagging, commit messages, and versioning. https://github.com/technomancy/leiningen/blob/master/doc/DEPLOY.md#releasing-simplified has details.
-- Daniel > On 21/11/2014, at 1:08 pm, Michael Cohen <mcohe...@gmail.com> wrote: > > 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 > > >> On 11/20/14, Greg Mitchell <metroidphr...@gmail.com> wrote: >> 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: >>> >>> Curious to hear opinions on this: >>> >>> https://github.com/mcohen01/amazonica >> >> -- >> 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 a topic in the >> Google Groups "Clojure" group. >> To unsubscribe from this topic, visit >> https://groups.google.com/d/topic/clojure/QcGi4lPYi1s/unsubscribe. >> To unsubscribe from this group and all its topics, send an email to >> clojure+unsubscr...@googlegroups.com. >> For more options, visit https://groups.google.com/d/optout. > > -- > 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. -- 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.
