Skip to content

Latest commit

 

History

History
90 lines (53 loc) · 5.8 KB

CONTRIBUTING.md

File metadata and controls

90 lines (53 loc) · 5.8 KB
Raw

Contributing to LogRhythm.Tools

LogRhythm.Tools has a master branch for stable releases and a develop branch for daily development. New features and fixes are always submitted to the develop branch.

This project follows standard GitHub flow. Please learn and be familiar with how to use Git, how to create a fork of the repository, and how to submit a Pull Request. Contributors are likely willing to help you with using Git if you ask questions in our slack channel #srf-community.

After you submit a PR, Project maintainers and contributors will review and discuss your changes, and provide constructive feedback. Once reviewed successfully, your PR will be merged into the development branch.

Commits

Golen Rule: One change, one commit

  • Commits should be atmomic.
  • An atomic change is an indivisible change — it can succeed entirely or it can fail entirely, but it cannot partly succeed.
  • The change should represent a piece of functionality that can be replayed over and over against a specific set of premises.
  • A change should be able to be reverted (git-revert) and not cause any side effects or conflicts in other parts of the system other than the one that is being reverted.

Pull Requests

Golden Rule: One pull request, one concern.

  • Each pull request should accomplish a clear goal.
    • Bug fixes: What was the bug? How did you fix it?
    • New features: What is it? How is it used?
  • A Pull Request represents a way to deliver value to the application in the form of a set of changes that together form a high-level concern.
  • Pull Requests should address a single concern, should be atomic, changing only that which is required to address the topic.
    • Keep requests small to support review, testing, and conflict resolution efforts minimal.
  • Pull Requests should not change things that are not directly concerned with the functionality that is being addressed.
  • Ensure your branch is up-to-date to reduce potential merge conflicts that could occur.
  • If changes such as whitespace, typo fixes, variable renaming, and the like are not related to the topic of the PR, they should be done in a different one.

Pull Request Rejection Criteria

Common criteria that will result in Pull Requests being rejected from LogRhythm.Tools:

  • Malicious code.
  • Code that does not align with the project's coding conventions.
  • Code that introduces breaks in established functionality.
  • Code that is plagiarized and/or violates terms of use of the origin author.

Coding Conventions

For detailed information on code style and conventions, please review the CODESTYLE.txt file.

Quick Guidelines

Here are a few simple rules and suggestions to remember when contributing to LogRhythm.Tools.

⛔ Do not commit code that you didn't personally write.

⛔ Do not use Write-Output.

☑️ File names must match the cmdlet name exactly, or will not be imported by the module.

☑️ Always use approved PowerShell verbs!

☑️ Try to include Pester tests along with your changes, or relevant updates to existing Pester tests.

☑️ Add comment-based help for your commands.

✔️ Please try to keep your PRs focused on a single topic and of a reasonable size.

✔️ Please try to write simple and descriptive commit messages.

✔️ Use or follow the general style provided by the templates found in the docs directory.

✔️ Try to use standard cmdlet parameter names wherever possible.

✔️ Generally avoid the use of [trap] - use try/catch blocks instead. For more information on error handling, this post is highly recommended.

About Command Output

For displaying information to a user, use Write-Host or, preferably, Write-Verbose. Never use Write-Output in any situation, unless there is a very specific reason to do so.

Use of Write-Host has been a controversial topic, in particular because of the limitations in doing anything with the output (redirect to stdout, etc) and confusion around what goes into the PowerShell pipeline. For the purposes of conveying information, we do not want that text getting into the pipeline.

Starting in Windows PowerShell 5.0, Write-Host is a wrapper for Write-Information, which is a structured information stream and can therefore can be used to transmit structured data between a script and its callers. This makes Write-Host useful for console messages without losing redirection functionality, and most importantly will not interfere with the PowerShell pipeline.

Example of redirecting Write-Host

PS> Write-Host "Somebody said today that I’m lazy. I nearly answered him." 6> c:\tmp\out.txt

Licensing

The LogRhythm.Tools project is under the Microsoft Public License unless a portion of code is explicitly stated elsewhere. See the LICENSE.txt file for more details.

The project accepts contributions in "good faith" that they are not bound to a conflicting license. By submitting a PR you agree to distribute your work under the Project's license and copyright.