Skip to content

Contributing.md

Latest commit

 

History

History
44 lines (29 loc) · 3.28 KB

Contributing.md

File metadata and controls

44 lines (29 loc) · 3.28 KB
Raw

Contributing to this project

Feel free to open an issue or pull request.

🚀 Publishing new versions

This project acts as a template repository in GitHub, meaning that as soon as a change is pushed to the main branch, it will be used when new GitHub repositories are created from this template.

This project also creates a PowerShell module that can be used to create new repositories. A prerelease version of the module is published to the PowerShell Gallery automatically on every commit to the main branch. The GitHub Actions deploy workflow run must be manually approved to publish a stable version.

Incrementing the version number

The version number is of the format Major.Minor.Patch and follows semantic versioning. By default, every commit to the main branch will increment the Patch version number.

If you want to increment the Major or Minor version number, you have 2 options:

  1. Manually start a deploy workflow run and specify the version number to use. e.g. Specifying 2.4.0 will produce a new version of 2.4.0.
  2. Create a new version tag and pushing it up to GitHub. Builds are not triggered on tags, and thus the version tag will be used as the starting point for the next version. e.g. Creating a new tag of v2.4.0 will produce a new version of 2.4.1 on the next commit to the main branch.

📄 Why are the template dot-files filenames prefixed with an underscore?

Publish-Module has a bug where it does not include any files or directories starting with . in the module NuGet package. The newer Publish-PSResource has fixed this issue somewhat so the directories and some of the files are included, but it still leaves out some dot-files, like the .gitignore and .editorconfig files. To work around these issues, we prefix the files with an underscore (e.g. _.gitignore) so that they are included in the module package, and then remove the underscore prefix during the file copy process of the New-PowerShellScriptModuleRepository cmdlet.

🧪 Smoke tests

The Smoke tests are used during the CI/CD workflow to verify that the module is working as expected after it is published to the gallery. The smoke tests are ran on Windows, MacOS, and Linux agents to ensure cross-platform compatibility, as well as against a Windows PowerShell 5.1 agent to ensure backward compatibility.

The difference between the smoke tests and the regular tests is that the smoke tests rely on the module actually being installed, not just the files being present. This means they can only test the functions and aliases that are exported from the module manifest and publicly accessible. This is the reason why we must use different files for the smoke tests than the regular tests; regular tests can test private functions and variables, but smoke tests cannot.

⁉ Why was a specific decision made

Curious about some of the choices made in this project? The reasons may be documented in the Architecture Decision Records.