If you're unsure or afraid of anything, just ask or submit the issue or pull request anyways. No one is going to yell or condescend for giving your best effort. Everyone was new at some point and we're all just working together to make something cool. This project is a few years old now and it was one of my first real open source projects. But I still feel like a complete novice maintaining it and I'm constantly learning new things. So no worries!
I'm the first to admit that I don't test nearly as much as I should. If you run into bugs, weirdness, or something just doesn't make sense, submit a new Issue. Even if you just need some help using the module, a generic issue is fine.
The native module help is now generated by platyPS from the Markdown files in docs/Functions. So if you want to contribute fixes or improvements, submit a pull request with changes to those files.
If you are editing the files locally, you can optionally install and generate the updated MAML XML help with platyPS as follows.
- Make sure the latest platyPS release is installed
- From the repository root folder run
.\gen-maml.ps1 - Force re-import the module from the repository folder or run
.\instdev.ps1to install the dev version to the current user's profile - Run
Get-Help <function name>to see your changes
Including the updated MAML with your pull request is appreciated but not required.
In addition to the native module help, we have a documentation website at https://docs.dvolve.net/Posh-IBWAPI/ that is generated by MkDocs from the Markdown files in docs/. Fixes, improvements, and new guides are all welcome additions. So feel free to submit a pull request for those as well.
Testing the doc site changes locally is a bit more involved because MkDocs is written in Python. You'll need a recent Python 3.x environment plus some additional packages. Follow the MkDocs install guide and add the following additional packages with pip install <package>.
- mkdocs-material
- mkdocs-awesome-pages-plugin
- mike
Checkout the main branch of the repository and run mkdocs serve to self-host a copy of the current documentation site. The output of the command should tell you the URL to use.
The tests in this project now use Pester v5. My overall code coverage is still pretty low. So if you're handy at writing tests or have suggestions to improve the existing ones, suggestions and pull requests are most welcome. The recommended way to run the tests is in a separate PowerShell process due to some limitations in how Pester is able to test internal module stuff. For example:
cd \path\to\Posh-IBWAPI
# Windows PowerShell
powershell.exe -C "Invoke-Pester"
# PowerShell 7+
pwsh.exe -C "Invoke-Pester"Keep in mind, the tests should be able to pass on Windows with PowerShell as old as 5.1 with .NET 4.5.2. They should also pass with PowerShell 7+ on any OS.
I know there are loads of use cases I haven't considered. If you have an idea for a new feature or functionality change, submit an issue first so we can discuss it. I'd hate for you to waste time implementing a feature that I may never pull into the project.
I'm trying to keep this a pure PowerShell script module without any non-native dependencies. Keep in mind that this module supports both classic Windows PowerShell and the cross-platform PowerShell Core. So please try to avoid platform specific calls.
I'm not super strict about code formatting as long as it seems readable. I'm a bit OCD about removing white space at the end of lines in my own commits though. Just don't make huge commits that contain a bunch of whitespace or formatting changes.
There's nothing that makes me want to work on this project more than knowing people use it other than myself. Drop me a line on Twitter (@rmbolger) and tell your friends about it.