Refactor of ImportExcel project #1535
Closed
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- Move readme, images, examples, and docs under docs folder. - Move module source under ImportExcel subfolder. - Simplify use of `Import-LocalizedData` and reformat `strings.psd1`. - Add `build.ps1` as entry point for local and CI builds. - Compile .PS1 files into tested & released module to speed up imports.
- Add `RunTests.ps1` to configure and invoke Pester for local and CI test runs. - Update tests so that the compiled version of the module is loaded. - Fix intermittent failing `Export-Excel` test by supplying a static set of sample file system data. - Set minimum Pester version to v5.2.0. - Generate test results in nunit format to be included as annotations in GHA workflow summaries.
- Define separate steps in `ci.yml` for build, test, and publish test results. - Invoke `build.ps1` to compile module to be tested. - Invoke `RunTests.ps` to execute Pester tests and save results to `Output/testResults.xml`. - Run GitHub Action step to publish test results as annotations on the job. - Add `docs.yml` workflow for building and publishing docs as static site using GitHub Pages.
- Update `build.ps1` to update existing, and generate new MD help using platyPS. - Rename lower-case MD files to match the case of commands as exported from module. - Update numerous links in MD files. - Add `ImportExcel.md` as "Landing Page" for platyPS in case we setup updatable help later. - Add `mkdocs.yml` - Add the `.md` extension to `.gitattributes` to ensure consistent CRLF line endings between platforms.
- Add `devcontainer.json` and `Dockerfile` with all dependencies necessary to build and test the module, and work on docs with local web server provided by mkdocs. - Install platyPS during build if module not available in a local or CI build.
|
@joshooaj Thanks for the work and PR. Going to pass on this. If the module continues to grow and folks are experiencing perf hits , it'll be a good time to leverage your work. Thanks for the github action for the docs generation. Once that popped back on my radar I've seen several non-PowerShell projects using mkdocs. I will revisit it for ImportExcel and already working on implementing for another of my PowerShell modules. Thanks again! |
|
No worries @dfinke - I appreciate you taking the time to chat about it and I'm glad some of it might be useful in other projects. Cheers! |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR started as an effort to reduce the time to import the module by taking the PS1 files that were previously dot-sourced by the PSM1 during import and "compiling" them into the PSM1 file before testing or publishing. This results in a faster import time on all platforms, but it's most noticeable on Windows and PowerShell 5.1 as discussed in #1531.
The refactor loosely applies ideas I learned from the PowerShell community over the last few years and especially @devblackops and @RamblingCookieMonster, but with an effort to minimize the number of new dependencies for now so I haven't included the use of psake, or BuildHelpers/PowerShellBuild. In the future I think it would be nice to strategize on a tool / framework for better structuring discrete tasks during build/test.
While working on this, I found opportunities to improve the developer experience and docs as well, so the PR:
ImportModule/subfolder.docs/subfolder.Output/folder.RunTests.ps1as an entrypoint to setup and run tests against the compiled moduleI did not intend to change behavior or add/remove functionality with the exception of reducing the module import time, but I recognize that the scope of this PR carries a higher risk of unintended side effects than a more typical PR. Thank you @dfinke for your time today to review the changes - hopefully we can get some customer feedback to confirm that there are no unintended side effects when used with real data!