Style Guide

API compatibility

Currently, aws-okta is v0, so technically we can change the API however we want. However, this makes internal development from multiple sources difficult. It means the sequence of merging PRs and the conflict resolution thereof is more work.

So in general, we'd prefer if the API expanded rather than changed.

For example, say you'd like to add a parameter region to constructor function NewClient(). Instead of modifying the signature of NewClient(), add a new function NewClientWithRegion(region string) and have NewClient call NewClientWithRegion with a default region.

Eventually this leads to API sprawl, so instead of inventing NewClientWithRegionAndHTTPClient or something, it's probably the time to introduce something like NewClientWithOptions(opts ...ClientOpt).

Logging vs UI messages

lib code should use logrus's StandardLogger. Use Trace level for dumping lots of info (including perhaps sensitive data) (audience: coders who need to analyze e.g. HTTP traffic), Debug for very deep progress (audience: coders), and Info for general progress (audience: users trying to debug a problem).

UI code should use stderr to display messages and prompts, and stdout to show/print data (that might get piped).