duct

maxov 2020-08-19T05:37:29.356500Z

Hi all - been learning duct, and it’s really cool. But I feel that the beginner resources are a bit lacking, e.g. the guide doesn’t go into much depth about how duct actually works, the duct framework README is a bit terse, the core README is outdated on pretty major concepts (it still describes modules as returning a map with :req and :fn ). There’s also no good resource I could find (aside from scattered talks/blog posts) that serves as a consolidated introduction to duct and integrant. Would there be interest in a short book/longer user guide that goes into more depth and consolidates common duct usage patterns? Or maybe there’s a resource already like this I’m missing?

lukas.rychtecky 2020-08-19T11:24:41.378400Z

Hej, I wrote a small post about how to build a service with Duct. I hope it can help https://flexiana.com/2020/07/building-web-services-with-duct-1-part

👍 1
maxov 2020-08-19T16:33:57.379300Z

Thank you! This is quite nice

👍 1
maxov 2020-08-19T05:43:19.358Z

For a pretty major example, I think I browsed quite a few resources and didn’t ‘get’ that the final Integrant configuration map is created by folding over all the initiated profiles and modules (and that this map is completely separate from the supplied maps in e.g. config.edn) until I actually read the source

maxov 2020-08-19T05:47:27.359400Z

The duct framework README almost says this, but it says something like “the original configuration is initiated into an intermediate configuration”, which is confusing because it’s that’s not the same type of initiation that Integrant performs. Integrant initiates the configuration into a series of functions, which then act as middleware producing the final configuration

kwrooijen 2020-08-19T07:02:10.360500Z

One guide that's commonly hidden and probably the most up to date is this file https://github.com/duct-framework/docs/blob/master/GUIDE.rst

kwrooijen 2020-08-19T07:02:37.360900Z

It doesn't go into detail about how the module system works though

kwrooijen 2020-08-19T07:11:28.361700Z

Also, I wrote a small guide on the Duct Base config / Profiles / Modules for my colleagues a while back. I added it to the wiki. Maybe it'll be useful to others: https://github.com/duct-framework/duct/wiki/Configuration#duct-base-profiles-and-modules

👏 1
teodorlu 2020-08-26T16:11:56.023900Z

Today, it was useful for me! These are core concepts that I've struggled with. Thanks!

kwrooijen 2020-08-26T16:16:55.026Z

Good to hear 🙂

kwrooijen 2020-08-19T07:12:39.362800Z

However, the duct docs can use a lot of work. It's true that everything is very scattered at the moment. And a lot of outdated. It would be nice to clean everything up and only have a single source of documentation. I don't really have the authority to do that though 🙂

☝️ 4
kelveden 2020-08-19T07:48:12.369300Z

Having been using Duct for a year now, I'd concur with all of this. One area that is sorely lacking in documentation in my view is the Duct merge logic e.g. what effect profiles and the likes of ^:demote, ^:promote, ^:displace , ^:replace have - again, viewing the source helps a lot here but a more holistic view would be great. I've been meaning to create an explain-merge function for a while now. As for the module system, something that helped me understand them was, after viewing the source, realising that they're essentially just "configuration factories" (i.e. components for generating more config).

👍 1
kwrooijen 2020-08-19T08:04:39.374500Z

Another thing that I think would be extremely beneficial is key documentation. Right now if you use one of the duct-framework modules, you need to read the source to know what your options are. Since keywords don't support metadata you can't add docstrings. I was thinking of having something like an integerant_meta.edn file which holds keys + maps as values. e.g.

{:some/key {:doc "documentation for this ig/init-key",,,}}
Which would allow you to add any type of metadata that you want. It would be merged similar to the duct_hierarchy.edn file and access it like the following (:doc (ig/meta :some/key)) . However weavejester has noted that he doesn't want to solve a problem like this in integrant itself. Which is understandable. it could be a separate library but if it doesn't get accepted by weavejester as a "duct" solution, and doesn't get merged in the module projects, there won't be a point

kwrooijen 2020-08-19T08:05:34.374600Z

Most of this is documented in meta-merge, but I agree with you. Also demote / promote isn't part of meta-merge

2020-08-19T08:58:39.374900Z

also duct actually implements its own version of meta-merge

2020-08-19T09:02:35.377100Z

I definitely want docs on keys… though it’s arguably a clojure problem. It seems likely that spec/spec2 will at some point support doc strings… though who knows when that will be. Also I’d like a standardised way to document components, essentially on the defmethod, but that’s obviously a little awkward — not sure if there’s a good solution to this.

2020-08-19T09:03:24.378100Z

Totally agree on the wider issues of duct documentation. I also wonder if having the docs scattered across so many repos/places is useful. It would be useful to have some centralised docs somewhere.

maxov 2020-08-19T16:42:38.380800Z

This would be really cool.. one observation is that modules and profiles are used in a different context from most other integrant keys, and I feel a full documentation solution would somehow handle this too. But yeah, if it’s not accepted as a primary solution then I agree there’s not much point

maxov 2020-08-19T16:46:31.381400Z

Thanks for all the comments! Seems like many agree more centralized documentation would be helpful. Then I might try to write some open chapters of a duct book/guide, with burden of maintainability on me of course. If it ends up being good enough, then maybe it could be merged into the existing documentation structure. Writing helps me learn, and I already have quite a few notes on how duct works as a starter guide 😛

🙏 1
kwrooijen 2020-08-19T16:58:21.382100Z

The only risk is that if it doesn't get merged into the official stream, then we'll have another source of documentation

kwrooijen 2020-08-19T16:58:45.382400Z

I don't think that should dissuade you though

maxov 2020-08-19T18:48:51.382500Z

Ah yes, the old https://xkcd.com/927/

😄 1
maxov 2020-08-19T18:49:22.382800Z

If it doesn’t get merged, then I’d be happy to mark it as inactive and link to the existing documentation to prevent this

kwrooijen 2020-08-19T19:12:54.383Z

I'd just rebel