Your First Pull Request
Clone this wiki locally
Here are 8 basic steps to submitting a pull request, which is essentially asking to commit your code to the dbatools development repository. Overview
- Create a github account then download and install GitHub Desktop
- Fork the dbatools repository
- Open your fork in GitHub Desktop
- Create a branch based on the development branch
- Publish your branch
- Code up a storm
- Commit your code to your local repository
- Create a pull request to our development branch.
First, login with your GitHub username and password. Login
First, ensure that your email is filled out so that you can be Click Options ensure your email is listedlisted as as a contributor.
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. Make a fork of the dbatools repository
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. Clone your fork to GitHub Desktop
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. Choose the directory where your project will be cloned
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. Change your base
While you can commit straight to your master, the Next, make a branch"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.
Just click Publish. Some Then Publish your branch to your repotutorials say to do this last, but we prefer doing it earlier on, if only for disaster recovery.
Please ensure you've read the Code up a stormcoding 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
Truth is, it's subjective how often you commit. Sometimes we commit just a few lines, sometimes we commit huge chunks. Commit to branchThis StackOverflow discussion suggests one commit per "logically separate changeset". Other people say do it more often. It's up to you.
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 But Firstrequires command line knowledge).
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.
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. Now, commit to branchHere's a list of commits to give you an idea of summaries.
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.
We're so happy that you've decided to join us! Congrats!
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 a 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!