On this page

    Submitting A Pull Request

    Overview

    This page describes:

    TL;DR

    Here is a list for project specific instructions. These are more technical - pretty much what would have to be executed in the console.

    Project Instructions
    AtlassianPS https://github.com/AtlassianPS/AtlassianPS/blob/master/CONTRIBUTING.md
    AtlassianPS.Configuration https://github.com/AtlassianPS/AtlassianPS.Configuration/blob/master/CONTRIBUTING.md
    AtlassianPS.github.io https://github.com/AtlassianPS/AtlassianPS.github.io/blob/master/CONTRIBUTING.md
    BitbucketPS https://github.com/AtlassianPS/BitbucketPS/blob/master/CONTRIBUTING.md
    ConfluencePS https://github.com/AtlassianPS/ConfluencePS/blob/master/CONTRIBUTING.md
    HipchatPS https://github.com/AtlassianPS/HipchatPS/blob/master/CONTRIBUTING.md
    JiraAgilePS https://github.com/AtlassianPS/JiraAgilePS/blob/master/CONTRIBUTING.md
    JiraPS https://github.com/AtlassianPS/JiraPS/blob/master/CONTRIBUTING.md

    The Setup

    New to Git(Hub)?

    Tooling

    To make changes to the code or documentation and send it as a Pull Request, only one tool is required:

    • Git
      There are many different ways to install Git. Please google how to install it on your OS.
    • PowerShell
      Any version works. If you are using version 3 or 4, the PowerShellGet module must be installed.
    • InvokeBuild

    Additional required modules are installed when Invoke-Build is called.

    There are more tools that are not required, but will make life much easier. Such as:

    Tool Description
    Graphic Interfaces for Git Git can get messy. A nice UI can be helpful. This page contains some for you to use.
    Visual Studio Code This is the editor of choice for working with Powershell. The project contains settings to make life easier.
    PowerShell Extension for VSCode This extension provides rich PowerShell language support for Visual Studio Code. Now you can write and debug PowerShell scripts using the excellent IDE-like interface that Visual Studio Code provides.
    Plaster Module Plaster is a template-based file and project generator written in PowerShell.
    Pester Module Build Automation in PowerShell. Will be installed as a dependency with Invoke-Build.
    PlatyPS Write PowerShell External Help in Markdown.

    Getting Started

    Find Something To Contribute To

    If you are interested in contributing and have nothing specific in mind, we are looking for help here: Issue that are “Up-For-Grabs”.

    Forking And Branching

    GitHub fosters collaboration through the notion of pull requests. On GitHub, anyone can fork an existing repository into their own user account, where they can make private changes to their fork.

    Once you have your own version of the project, you should:

    ** powershell git clone https://github.com/<YOUR USER NAME>/<NAME OF THE PROJECT>.git **

    • Create a new branch for your changes You should make the changes in a branch for tracking them. You should also create your own branch out of develop. You can read more here: Git Flow Guide.

        cd <NAME OF THE PROJECT>
  git checkout develop
  git checkout -b <NAME FOR YOUR FEATURE>

    Additional references:

    Making Changes

    Getting Work Done

    We do not impose a specific way to write code.

    However, there are some Guidelines which should be followed at all times.

    The checklist when creating the Pull Request will look something like this:

    Types of changes:

    • Bug fix (non-breaking change which fixes an issue)
    • New feature (non-breaking change which adds functionality)
    • Breaking change (fix or feature that would cause existing functionality to change)
      Checklist:
    • My code follows the code style of this project.
    • I have added Pester Tests that describe what my changes should do.
    • I have updated the documentation accordingly.

    Documenting Your Work

    In general, PowerShell is verbose in a way that the code explains what it does. So, minimal code documentation is needed.

    When code is not easy to read or requires more extensive explaining (such as workarounds), use comments to explain what it does to make it more readable for others.

    All parts of the code that affect user interaction are expected to have detailed documentation. This includes (but is not limited to) Functions, Parameters and Output Types.

    It is also expected that the tests that describe the functionality are either updated or created, if the functionality is new.

    Additional material:

    Making Sure All Is Working

    The projects have several tests to ensure everything is working as expected. The tests are all in the /Tests/ folder.

    The projects are set up so that running Invoke-Build will make sure the code is working as the tests describe. The command must be run from the root of the project.

    Sending Your Changes

    Send A Pull Request

    When you are done and all tests pass, you can send the changes “upstream” (to the AtlassianPS project).

    Here is how you create the Pull Request: Creating a Pull Request

    What Happens Next?

    Now our maintainers and reviewers will look over what you submitted.

    To help them, the GitHub repositories will use CI jobs to run the tests and report if the submitted code is working as expected.

    Every Pull Request must be approved after review and the reviewer(s) might:

    • have some constructive feedback for your code and suggest optimizations (eg: adding Write-Verbose messages)
    • request you to make specific changes before approving it (eg: adding tests)
    • request changes to the documentation (eg: add a new example to the function)
    • push some changes to your code (eg: harmonize some code)
      By default, github grants “write” permissions to the reviewers to your fork. You can disable this, if you wish.

    Once the reviewer approves your Pull Request, it will be merged into the develop branch and part of the next release.