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 first to your local repo if you created a branch, then ultimately, to ctrlbold/dbatools.

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

 

Next, make a branch

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

To learn more about branching, click here.

 

Then Publish your branch to your repo

Just click Publish. Some tutorials say to do this last, but if you would like a code review along the way, the branch will have to be public.

 

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!

 

Commit to branch

I think it's subjective how often you commit. Sometimes I commit just a few lines, sometimes I 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.

One of the best pieces of advice that I 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. I add a description probably once every 20 commits if I can't sum up my commit well in the summary. Here's a list of commits to give you an idea of summaries.

 

But First!

If 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).

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

 

Now, commit to branch!

 

Create your pull request!

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

From here, I'll likely either ask you to make a few changes, or accept the pull the make them myself. There are some style particulars that are hard to convey here, so I'll add them.

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