Skip to content

Latest commit

 

History

History
72 lines (41 loc) · 5.49 KB

CONTRIBUTING.md

File metadata and controls

72 lines (41 loc) · 5.49 KB
Raw

IMPORTANT

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 my first real open source project. But I still feel like a complete novice maintaining it and I'm constantly learning new things. So no worries!

How to Help

Submit Issues

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. I also check the Let's Encrypt community forums (@rmbolger) fairly regularly if you prefer that format.

DNS Plugins

If you want your provider supported but can't write the plugin yourself, submit an issue with the request and I'm happy to give it a try. But the hardest part about writing new DNS plugins is usually getting an account with the provider to test with. Providers with free trials or sandbox/test environments are great. Otherwise, I just need temporary access to an existing account or a donation to cover the cost of setting up a new account with the provider.

Pull requests for plugins you've written are also encouraged. I still try and test them myself before merging them which goes back to the hassles of getting an account with the provider to test with. But that's mostly so that I'm confident I can support the plugin long term without needing to pull you back in to support it if someone submits and issue with it.

Native Module Help

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.ps1 to 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.

Documentation Website

In addition to the native module help, we have a documentation website at https://poshac.me/docs/ that is generated by MkDocs from the Markdown files in docs/. Fixes, improvements, new guides, and new links to external articles 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.

Unit Tests

The tests in this project now use Pester v5. You will also need to have the Microsoft.PowerShell.SecretManagement module installed, but no vault extension modules or configuration is required.

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-ACME

# Windows PowerShell
powershell.exe -C "Invoke-Pester"

# PowerShell 6+
pwsh.exe -C "Invoke-Pester"

Keep in mind, the tests should be able to pass on both Windows PowerShell 5.1 and PowerShell 6+ on any OS.

Features and Functionality

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.

Code Guidelines

I'm trying to keep this module as close to pure PowerShell as possible. Avoid binary dependencies or other module dependencies unless there's no other choice. Try to avoid blocks of C# code loaded via Add-Type. Favor programmatic solutions over calling external executables when possible.

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.

Say Hi and Tell Your Friends

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.