feat: Update package structure

[OlaoluwaM]

To be more aligned with other Freckle OS packages

[pbrisbin]

There might have been some confusion here.

If we're offering a general-purpose library for use by anyone in any context, we wouldn't prefix anything. Test.Hspec.Expectation.JSON, Graphula, Control.Monad.AWS, etc, etc. These are all just packages we author.

freckle-app is unique, in that it's "Freckle's SDK for Apps". "Freckle" in that case was less of a namespace, or to describe ownership, and more part of the name of the library.

Then we started extracting things from freckle-app. I would probably not have prefixed all the now-generic stuff that came out of there (e.g. freckle-http), but I think Chris did so out of expediency, with plans to rename later. So those are not good examples.

So in this case, I don't think we want Freckle.. (And if we did, we'd also rename the package to freckle-, I think.)

That said, there are other common naming conventions in Haskell that may be appropriate here, such as Data. or Network. (this package may use both). I don't have strong feelings.

I also see the package is named cloudevents (plural) and then the top-level of the module tree is CloudEvent (singular), so maybe that's worth fixing.

🤷

[OlaoluwaM]

Thank you for the clarification @pbrisbin

That said, there are other common naming conventions in Haskell that may be appropriate here, such as Data. or Network. (this package may use both). I don't have strong feelings.

Where can I learn more about these conventions?

I also see the package is named cloudevents (plural) and then the top-level of the module tree is CloudEvent (singular), so maybe that's worth fixing.

Well, the spec itself is called "cloudevents" so I opted to use that in the package name for discoverability. Moreover, the plurality, IMO, also signals that this package is meant for all things cloudevent related (at least, that's the goal).

As for the top-level directory being singular, I made it that way to represent that users of the library would be working with APIs from the perspective of a single cloud event representation. I was also influenced by the JS SDK which uses the singluar naming: https://github.com/cloudevents/sdk-javascript/blob/main/src/event/cloudevent.ts

I'm unsure whether this makes sense but that was my reasoning 😅.

[pbrisbin]

Where can I learn more about these conventions?

I don't know, they're kind of loose and not uniformly followed.

the spec itself is called "cloudevents"

I agree the package should be cloudevents.

the perspective of a single cloud event representation

I think that's what the Event module is doing, that is singular and is the data type you work with to represent a single event. As far as I can tell, you're using CloudEvent. as a namespace, in which case I would personally always make it match the package name. I think to follow the JS SDK, you'd have a module like CloudEvents.Event.CloudEvent -- in other words, the JS SDK doesn't have a top-level namespace, so what we use is up to us, then Event.CloudEvent is how we are following it within.

[pbrisbin]

Alternatively, I could see doing something like:

• Data.CloudEvent -- the event type you work with
• Network.CloudEvents -- code for sending such eventS

But I don't think I like this. I like putting everything under {PackageName}. unless there is a strong reason not to, such as how we use Control.Monad.AWS to show a clear relationship with other Control.Monad. things.

This is pretty subjective, so feel free to solicit other opinions.

[OlaoluwaM]

Yeah, it seems to me like this is a very intuition driven thing and I since I lack the necessary intuition (at least for now) I don't really have any hard and fast opinions 😅. If anything I'll just go with whatever you think is best then try to develop my intuition from there (though, arguably I probably should have been paying attention to all those Haskell packages I've used/been using....)

[pbrisbin]

I think following the js-sdk makes the most sense, as you thought originally. Using that would look like,

import x from "cloudevents/event/cloudevent"

Right? If so, then I think you would agree that

import CloudEvents.Event.CloudEvent (x)

Would be the most accurate Haskell port.