Your First Pull Request

Overview

Here are 8 basic steps to submitting a pull request, which is essentially asking to commit your code to the dbatools development repository.

1. Create a github account then download and install GitHub Desktop
2. Fork the dbatools repository
3. Open your fork in GitHub Desktop
4. Create a branch
5. Publish your branch
6. Code up a storm
7. Commit your code to your local repository
8. Create a pull request to our development branch.

Login

First, login with your GitHub username and password.

Click Options ensure your email is listed

First, ensure that your email is filled out so that you can be listed as as a contributor.

Make a fork of the dbatools repository

Because you don't have write permissions to the repository, you'll have to fork it to your own repo, and do your commits there.

Clone your fork to GitHub Desktop

Now you have to download your fork so that you can begin to make changes. Go to your repo, click on the dbatools fork, then click Clone or Download then Open in Desktop.

Choose the directory where your project will be cloned

Remember that where ever you save the project, you will need to import the module from there (ex. Import-Module C:\GitHub\dbatools\dbatools.psd1). If you already have dbatools installed, consider uninstalling/deleting it so that you don't get confused.

Change your base

Now that the repo has been cloned, ensure you're starting from the proper branch. We recommend developing from the **sqlcollaborative/development** branch because that has the latest changes. The master branch only gets updated once a month. The development branch will also be the branch that you submit your Pull Requests to.

Next, make a branch

While you can commit straight to your master, the "proper way" is to create a branch first. Name your branch something useful like bugfix-agentjobs or feature-orphanedusers.

To learn more about branching, click here. We find branches extraordinarily useful when we're working on multiple issues. It's a way to isolate your changes.

Then Publish your branch to your repo

Just click Publish. Some tutorials say to do this last, but we prefer doing it earlier on, if only for disaster recovery.

Code up a storm

Please ensure you've read the coding guidelines. Examine some of the functions to get familiar with the way dbatools is coded. If you have questions, we're more than happy to answer! If you're having design questions, don't be afraid to ask. This is a learning experience for all of us and the more SQL PowerShell coders we've got out there, the better!

Basically, this is what you'll do if you're working on a new command

• Add your new command to the functions subdirectory, in the format of Verb-DbaNoun.ps1
• Add your new command name to the list of Functions in FunctionsToExport in dbatools.psd1
• Reload the module with -Force

Commit to branch

Truth is, it's subjective how often you commit. Sometimes we commit just a few lines, sometimes we commit huge chunks. This StackOverflow discussion suggests one commit per "logically separate changeset". Other people say do it more often. It's up to you.

But First

As mentioned earlier, when you are working on a new command, you will need to modify your local **dbatools.psd1** so that your new command will be exported. Please do not commit the dbatools.psd1 or the Pull Request will be refused until dbatools.psd1 has been removed (which [requires command line knowledge](https://github.com/sqlcollaborative/dbatools/wiki/uncommit-psd1)).

To avoid committing the psd1, you can either discard the changes (but you'll have to put them back) or simply uncheck the box and don't commit it.

Now, commit to branch

One of the best pieces of advice that we've read was "you always have enough time to compose a meaningful commit message." It's true. Please make your summary meaningful. Not necessarily long, just meaningful. We tend to add a description probably once every 20 commits if we can't sum up the commit well in the summary. Here's a list of commits to give you an idea of summaries.

Sync Up

Hit that Sync button so that you have the latest changes, and GitHub has your latest changes.

Create your Pull Request

Create your Pull Request, ensuring that you are requesting to pull into sqlcollaborative/dbatools/development.

If your code fixes an issue, please include the issue # in your PR (like "Updated SQL query in Copy-SqlDatabase. Fixes #311"). GitHub will then magically link the two.

Congrats!

We're so happy that you've decided to join us!

From here, there are a few additional steps

• A code review is performed by Chrissy LeMaire or another member of the code review team
• QA is performed by Daniel Alexander or another member of the QA team
• Your Pull Request will be approved after all required changes are performed
• As for changes, subsequent commits to your branch that you perform at our request will automatically update the Pull Request in the repository
• Your additions will be merged with master during the next release

Thank you for helping to enhance the SQL Server DBA community!