[FP] New-ModuleSkeleton

[bravo-kernel]

As a possible approach for PotentialContribution/ModuleCreation I have created a working demo branch that generates a fresh module following ModuleBuilder best practices.

The code is obviously just to make things work. If desired I could go forth and create a proper PR to get things started for real. Motivation bulleted in the code New-ModuleSkeleton source. The intended 30-second-up-and-running user story would be something like:

1. install ModuleBuilder
2. run New-ModuleSkeleton -Name MyNewModule
3. cd MyNewModule
4. build
5. Get-HelloMyNewModule (optional)

Also:

• commit ready
• azure pipelines ready
• pester ready

Please let me know

[Jaykul]

I know that the people who've contributed are using a lot of different ways to create new modules, from Plaster, to dotnet templates (my personal preference).

I don't think I want to create a new way of generating the framework for a module. I'd like to support one that's already out there.

I'd been thinking along the lines of creating a Module Bundle (or two or three) including different sets: For instance, a {Plaster, ModuleBuilder, Psake} bundle with a template for Plaster that includes a Psake build script, etc. And then a {Invoke-Build, ModuleBuilder, dotnet} bundle with a dotnet template and invoke-build build script, etc. What do you think of that?

As a postscript: I'd love to have just the template parts of dotnet as a module, instead of requiring the dotnet SDK...

[bravo-kernel]

Thanks for the elaborate feedback. I will look into your suggestions and report back here soon. Hopefully we can use this ticket to come to a solution that is acceptable.

Just to be sure: I am only looking for a way to generate new modules fast and solid, adhering to the formats and structure that ModuleBuilder expects. The easier it is to generate those modules, the higher the adoption rate of ModuleBuilder itself will be IMO, FYI it took me more time than may be expected from new users to start prototyping (no offense).

[Jaykul]

There's a template for dotnet from my day job: https://github.com/questionmark/PowerShellTemplate/

[bravo-kernel]

I think I'm beginning to see what you mean and must say that I like it. The more use of proven tools the better. Following your example of supporting two "builders" my intuition says:

• this would have to become a single Bundle, supporting multiple builders
• this because all builders will share:
  • the same folder structure
  • blueprint files
  • build-tasks/functions
• this way a fix for e.g. blueprint file .gitignore would apply to all builders

Does this come close?

To be honest I was not able to find any information on how to use/incorporate the "Bundle" so a pointer would be highly appreciated. Am I correct in that the bundle would become a separate repo, somehow pulled in as a required module by ModuleBuilder?

[Jaykul]

A PoshCode bundle is just a metadata file listing a set of modules, so that's trivial, we just make lists ...

As far as a template, I think it makes sense to have a single source project, but I'm not actually sure how it would work:

• In Plaster you write template code in files which has it's own syntax, etc.
• In dotnet's templates, the template is just an example of the output you want from the template, plus a config file.

In theory, you could write a plaster template, and use the output of the plaster template as the dotnet template -- but that hurts my brains a little.

Finally, I'm not sure the bundles need to include the templates -- I think each of those tools like plaster, dotnet new, etc have their own built-in methods for finding templates online.

[bravo-kernel]

To prevent over-engineering and given the fact that the end-user will probably not care about what solution is used under the hood:

• why not pick a single solution (e.g. Plaster)?
• use that to generate the initial module skeleton following ModuleBuilder best practices
• (optionally) wrap it in a command that comes with ModuleBuilder

Understandable and only a single source to maintain. Also, as far as I have read thus far the Plaster template should be detected automatically if installed along with ModuleBuilder.

[Jaykul]

Well, I'm slightly allergic to making decisions for other people about what tools they have to use ...

That is to say:

1. We absolutely should have a Plaster template
2. I don't want to force people to install Plaster

So, I would love it if you put together a plaster template.

I would love it even more if you can work with @JPRuskin -- he did the initial work on questionmark/PowerShellTemplate, and we can create two solutions which end up with the same template output.

[bravo-kernel]

Installing Plaster as one of the ModuleBuilder RequiredModules would indeed be the logical result but to be honest I didn't see any harm in that (coming from other languages using exactly that approach for their installers).

Anyway, I will follow your advise and will create a mock Plaster version, perhaps we can take it from there.

[Jaykul]

I think my ideal scenario would be to:

1. Create a "Plaster" folder here to contain the Plaster template(s)
2. Make that into a module with just one command: New-Module, and a dependency on ModuleBuilder and Plaster, and maybe Pester and ScriptAnalyzer...
3. Update the ReadMe to recommend people people install "ModuleBuilderWithPlaster" (or whatever we call it) instead of just ModuleBuilder, as an easier way to get started.
4. Publish both modules whenever we update ModuleBuilder

and then ...

5. Create a dotnet-new folder ... and repeat steps 2..4
6. Maybe create a yeoman folder ... and repeat steps 2..4

I think the reality is that most developers don't actually use scaffolding tools like Plaster (or Yeoman, even though it has a lot of users) long term, but they can be super helpful when you're first learning a new language or framework.

[bravo-kernel]

✅ Glad to see point 3 confirmed, that's why I started this in the first place. Also, your suggestion makes sense now, I was thinking of not including the scaffolding tool itself as part of the skeleton.

Anyway, thanks for taking the time to talk this through. I will try to come up with a mock Plaster version, inside this repository, placed in a "Templates\Plaster" folder.

[bravo-kernel]

To make things visible I have uploaded a working proof of concept in my generators branch. The readmes in the Generators and Generators\Plaster folders contain additional motivation but after testing various variations I eventually felt most comfortable with this approach and think it matches with the topics discussed above:

1. use the Dotnet template(s) as the base for all other generators (since it is a working copy anyway)
2. if needed, use a per-generator build.ps1 to construct the module for that specific generator

Obviously the code and naming should be be ignored but it works as can be seen here:

What do you folks think? All feedback welcome and ready to discuss (where? @JPRuskin?)

[bravo-kernel]

Also, I think it would be nice/wise if we could pick some files from the main repository while constructing the generator modules. For example GitVersion.yml would make a good candidate, PR's on that file would transpile into the generator modules.

[Jaykul]

Been crazy busy the last couple days, might be next Wed before I have a chance to look at this, unless I can make time while traveling this weekend.

You could probably use symbolic links for including files.

[bravo-kernel]

No rush

[bravo-kernel]

To make things visible I've added a single symlink in the PoC branch for the GitVersion.yml file.

I am split on whether this would be the way to go though. One the one-hand symlinks make total sense from a Linux standpoint (the one above was created in Ubuntu). On the other hand the drawbacks and caveats of using symlinks on Windows makes it a bit too funky for my personal taste. Perhaps it also triggers your allergy:

• no mklink on my current windows machine (git bash 2.14.1.windows.1)
• no admin rights whatsoever in my Powershell
• copying symlinks without the above creates exact-copies of the gitted symlink files (and thus with the relative filepath in them)
• no git pull updating etc

You are obviously aware of these points since you provided the symbolic links page yourself but I feel this solution would lead to a situation one can less reason about. Agreed, the alternative is not perfect either but IMO a simple and well described copy-paste action before creating the templates is something any contributor would instantly understand and would work on all platforms without doubt, something to consider.

Open to all suggestions, not trying to irritate anyone either btw, just chasing the best solution for this clearly very potential repo.

[Jaykul]

• mklink is a DOS command. In PowerShell you use New-Item -Type SymbolicLink
• Permissions have not been an issue since Windows 10 Creators Edition if you're in Developer Mode (you should be, if you write code)

I don't mind copying the file during build though, that would be fine?

P.S. Your git is out of date, but I think even it's new enough to copy symlinks, no?

[bravo-kernel]

✅ on not using symlinks.

You are correct that my Git is out of date but... for a reason. I realize that this is a preference but I like to keep my Windows system as vanilla as possible with the software as low as possible. This enforces me to be an end-user and makes most assumption-based errors instantly visible.

No mistake, I develop for a lot of Operating Systems and languages but use Virtual Machines, actual servers and CI to keep those in check. For the end-user experience... I use my PC.

[bravo-kernel]

Closing as a PR #77 is now open