reconcile reagent-template and reagent-seed

[porcuquine]

It's confusing that reagent-project provides both reagent-template and reagent-cookbook, but the latter seems to prefer reagent-seed. Even though there may be plausible use cases for two templates, it's hard as a newcomer to know how to start a new project. For example, I ended up creating multiple projects then eventually manually merging them.

[gadfly361]

Yeah, I can see that being confusing as well. I originally decided to use reagent-seed as the starting point for recipes for the following reasons:

1. I am the maintainer of reagent-seed, so it is easier for me to make sure the reagent-cookbook recipes still work when reagent-seed template goes through updates.
2. The starting point of reagent-seed has a few more things included (at least in terms of the src/ directory) than reagent-template does, which makes it easier to 'hit the ground running'.

That said, I would be happy to change the starting point of recipes to reagent-template if there is consensus. The only thing I might recommend is that reagent-template add an option like +cb to allow for a more advanced starting point.

Thoughts?

[Frozenlock]

What are the additional features that would be provided by +cb? Garden?

[porcuquine]

I think one template with options would be fine, maybe perfect, ideally such that the options could be added later (i.e. the structures are compatible).

I think figwheel support should be included in whichever template is used.

The main point is that there should be an unambiguous path for starting a new project before you have a good feeling for the moving parts involved. As it stands, you have to make guesses and possibly backtrack.

[Frozenlock]

I think figwheel support should be included in whichever template is used.

Should it?

If anything, I think the cookbook should use a template (or a template profile) which is really minimal. (No secretary and other whistles.)

This way, the user can immediately see what is relevant.

[porcuquine]

I see your point, but then the template is really just serving as documentation and not an actual intended starting point. Since it's extremely helpful to have an actual, good-enough starting point, the cookbook may as well use it (whatever it is) as a base. Individual recipes could make their actual dependencies explicit for those who aren't using the template as such.

Whether figwheel needs to be in the recommended starter template is a slightly different question. I would argue that it should, though.

[gadfly361]

Originally I was thinking the recipes needed to have multiple namespaces to separate out concerns like in reagent-seed, but I think I am no longer sold on that idea. I agree with @Frozenlock that a more minimal approach is likely better, because it will improve the signal-to-noise ratio.

For convenience, I think we should use reagent-template as the starting point for the recipes since that is the official entry point into a reagent application. Since secretary is already included in reagent-template, I think we can leave it in. As for Garden, we can probably leave it out of the template, but for any recipe that I write, I will just recommend its use.

[Frozenlock]

I wouldn't be opposed to removing secretary from reagent-template. I left it in the +lib version because I didn't want to mess with @yogthos example code, but perhaps it's better to write a more light dummy-code.

I really love the idea of a template with multiple options/profiles.

+cljx for a cljx project, +lib (or inversely, +app) to determine if the dependencies should be moved into the :dev or :uberjar profile +all-the-shits for all the bells and whistles you could want :-) etc...

[gadfly361]

:+1:

If we embrace the idea of options/profiles, then I wouldn't be opposed to dropping secretary from the default lein new reagent <name> case either. Should improve the readability of the recipes quite a bit.

[yogthos]

The profiles idea worked out well for Luminus and looks like Duct has adopted them as well. I would definitely be up for going down that road and having a minimal template that can be extended with routing and so on.

[gadfly361]

Sounds good! Once that is ready, I'll go ahead and transfer all of the current recipes over to reagent-template.

[gadfly361]

I thought about this for a while, and I think having a profile in reagent-template that is bare-bones wouldn't work for recipes. First, reagent-template is subject to some change. And second, I think even a bare-bones version of reagent-template would contain too much unnecessary stuff that could potentially dilute the intent of the recipe (much like how reagent-seed diluted the intent of the recipe).

So with that in mind, I made reagent-cookbook-template, which is meant specifically for recipes and to be used in development.

[yogthos]

Yeah, I really like how minimal the new examples are. I think it's important for people to be able to focus on the example without any additional distraction. :+1: for a cookbook template. ;)

[porcuquine]

This probably addresses my initial concern as well. The main point is that naming and documentation should provide a simple and unambiguous suggested template for someone inexperienced who just wants to get started on a new project.

It seems that this recommendation should be reagent-template and that it need not be too minimalist. Rather, it should provide a reasonable guess at a good starting configuration.

WIth the naming change, it should be obvious that the cookbook template exists to facilitate clean expression of cookbook recipes.

That would address my problem, as long as documentation and descriptions here and elsewhere also reinforce the distinction.

[gadfly361]

@clkunzang I added the following to the README, does this work for you?

---

The starting point for reagent-cookbook recipes is reagent-cookbook-template.

$ lein new rc <name of recipe>

Note: reagent-cookbook-template was made specifically for following along with recipes - it is not meant for production. If you are interested in starting a new reagent application, then reagent-template provides a good starting configuration: $ lein new reagent <name of app>.

[porcuquine]

Yes, that's perfect.

[gadfly361]

Awesome, thanks for helping provide clarity with the template situation! I think this is a big improvement. I am going to go ahead and close this issue.