Contributing to aws-beam/aws-elixir

That’s a great idea @mbuhot!

I have started looking at aws-beam and what it would be necessary for me personally to migrate to it and I have found some action items:

1. Migrate from poiston to jason
2. Make the HTTP client pluggable (similar to what is done in ExAWS)

I was planning to send a PR for those but I decided to post them there as folks are looking for ways to contribute. It is probably worth checking out with the maintainer too if they welcome these changes before moving forward.

I’ve started depot_s3 using ex_aws. If anyone wants to give it a shot at moving to aws-elixir that would be welcome as well:

https://github.com/elixir-depot/depot_s3

What about adding documentation?

Based on what’s in the GitHub repo for it, there’s no docs other than 1 example.

Having to install the library and generate your own docs seems like a weird burden to put onto the developer.

Maybe a PR could be made to auto-generate the docs in GitHub Actions?

I would suggest one more thing - instead of generating Elixir and Erlang libraries, generate only one and make the other one wrapper around another.

As most Elixir projects, the docs are on hexdocs: aws-elixir v1.0.13 — Documentation - The README could make it clearer though, probably a good opportunity for a first PR. Go for it!

Given it is auto-generated, I don’t see an issue with generating both. Especially because Erlang developers do not want to bring Elixir as a dependency and Elixir developers don’t want to lose the nicely generated ExDoc documentation we have today.

Thanks, I didn’t think to check there because it wasn’t linked.

Although it’s kind of non-intuitive because even after clicking your link, I thought the docs were literally all of what we see on that first hex page you linked. In other words, just a list of services with no other information. There’s no visual hint that those AWS services are links on Hex.

Funny enough the only service I wanted to use is S3, but there’s no docs for S3 too.

I know I fall back to comparing things to Python a lot but this is the documentation for the Python AWS library Boto3 1.43.38 documentation. There’s hundreds of real code examples which I think is fantastic, along with a few practical getting started guides.

This Elixir library’s docs are an API spec. Unfortunately there’s 0 examples on how to use anything. This makes it very hard to figure out how to use it unless you’re already a seasoned veteran.

It’s one of those things where I would contribute if I knew how, but I can’t figure it out because there’s no existing documentation. That and I suppose in this library’s case if the API specs are auto-generated, then maybe there’s no way to modify the docs since the code is generated and is expected to be read-only by humans?

There is one issue - both projects register application named aws, which mean that when you will (for some reason) application that uses Erlang dependency that is using Erlang version and you are using Elixir version then there will be name conflict. With making Elixir wrapper over Erlang library it could be mitigated by using different name for the wrapper (as it would cause no problems there).

It seems you have a list of improvements and a reference, so that’s a great opportunity to act on it! I have sent a PR with some changes too. AWS.S3 does exist, the docs may be outdated.

Yeah, this definitely should not be the case. I think it is an orthogonal discussion to wrapping though.

I am not 100% sure as there is some “handwritten” code in the both repos (utilities and credentials). I think that making it unified (either as a additional Erlang repo or by incorporating everything into single repo with wrapper) would help with reducing area of possible bugs.

I wouldn’t even know how to begin. Wouldn’t you need write access to publish the library to update the docs on Hex? I’m also confused how auto-generated code can emit out of date documentation. Aren’t the docs based on the source code or is there a separate step? I’ve never published a package on Hex.

As for adding code examples to improve the docs. It’s a catch-22. I can’t add examples until I learn to use the library but I can’t learn to use the library because there’s no practical examples.