forked from dataplat/dbatools
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
updated contributing.md with new contrib info
- Loading branch information
1 parent
a2a9822
commit d385ea8
Showing
1 changed file
with
75 additions
and
55 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,80 +1,100 @@ | ||
| # Contributing.md | ||
| This is the contribute.md of our project. Great to have you here! Here are a few ways you can help make this project better. | ||
| Here, we'll help you understand how to contribute to the project, and talk about fun stuff like styles and guidelines. | ||
|
|
||
| ## Team members | ||
| # Contributing | ||
| Let's sum this up saying that we'd love your help. We're slowly getting ready for the 1.0 release albeit a bit too slowly! | ||
|
|
||
| We've got over 20 Major Contributors to the dbatools project! Check us out on [the Team page](https://dbatools.io/team) and on [LinkedIn](https://dbatools.io/company). | ||
| There are several ways to contribute: | ||
| - Create new commands (PowerShell/T-SQL knowledge required) | ||
| - Report bugs (everyone can do it) | ||
| - Tests (Pester knowledge required) | ||
| - Documentation: functions, website, this guide, everything can be improved (everyone can) | ||
| - Code review (PowerShell/T-SQL knowledge required) | ||
|
|
||
| There area number of ways to become Major Contributor which includes getting your mug & link to your blog/twitter on dbatools.io and adding dbatools to your experience on LinkedIn and your resume! Major Contributors of dbatools have done at least one of the following: | ||
| If you wanna help reaching 1.0 | ||
| - Standardize param names (@wsmelton) | ||
| - Create tests for existing functions (@cl and @niphlod) | ||
| - Review existing function documentation (@alevyinroc or @gbargsley) | ||
| - Prepare for 1.0 with "code style" (Bill of Health, more on that later) | ||
|
|
||
| * Contributed one approved command | ||
| * Added over 100 lines of code | ||
| * Setup Jenkins for continuous integration | ||
| * Became a designated tester | ||
| * Added lots of/fixed documentation | ||
| * Fixed some super hard bugs | ||
| * Presented about dbatools multiple times | ||
| We strive to make any area doubtless. In any case, the Slack channel is pretty active and every area has one (or more) volunteers to refer to in case of doubts. | ||
|
|
||
| We aim to be **inclusive**. If you'd like to become a Major Contributor, just let us know your intent and we'll help get you there. | ||
| ## Documentation | ||
| Documentation is really the area we welcome any help possible. The documentation refers to both the CBH (Comment Based Help) and the [website documentation](https://dbatools.io/functions). The CBH documentation is included with each command and is the content you see when you run `Get-Help Function-Name`. If any of that content is not clear enough or if the examples in the functions are not working, you should say so (e.g. raise an issue on GitHub or comment in Slack). Even if you are a casual user or a PowerShell newbie, we need your angle to make it as straight forward and clear as possible. | ||
|
|
||
| ## Learn & Hangout | ||
| ## Contribute New Commands | ||
| Start out reviewing the [list of functions on the website](https://dbatools.io/functions/), or pulling the list from the module with `Get-Command -Module dbatools -CommandType Function | Out-GridView`. If you find something similar already exists, open [a new issue on GitHub](https://GitHub.com/sqlcollaborative/dbatools/issues/new) to request an enhancement to that command. New ideas already accepted can be found on [New Command](https://github.com/sqlcollaborative/dbatools/labels/Type%3A%20New%20Command) tagged issues. If nothing similar pops up, either ping @cl on Slack with your idea about the new command or open a new issue on GitHub with details or requirements you need. | ||
|
|
||
| Want to join the team or just come hang out? You can find us here: | ||
| ## Report Bugs | ||
| [Open a new issue](https://GitHub.com/sqlcollaborative/dbatools/issues/new) on GitHub and fill in all the details. The title should report the affected function, followed by a brief description (e.g. _Get-DbaDatabase - Add property x to default view_). The provided template holds most of the details coders need to fix the issue. | ||
|
|
||
| * Slack: #dbatools on the [SQL Server Community Slack](https://dbatools.io/slack) | ||
| * Blog: [our blog](https://dbatools.io/blog) | ||
| * Twitter: [we tweet, too](https://dbatools.io/twitter) | ||
| * YouTube: [and we've got some videos](https://dbatools.io/youtube) | ||
| * LinkedIn: [our "company" page](https://dbatools.io/company) | ||
| ## Fix Bugs | ||
| TODO: do we have an "how to open a PR" guide somewhere ? | ||
| [Open a PR](https://GitHub.com/sqlcollaborative/dbatools/pulls) targeting ideally just one ps1 file (the PR needs to target the *development* branch), with the name of the function being fixed as a title. Everyone will chime in reviewing the code and either approve the PR or request changes. The more targeted and focused the PR, the easier to merge, the fastest to go into the next release. Keep them as simple as possible to speed up the process. | ||
|
|
||
| ## Adding new commands and features | ||
| ## Standardize Parameters and Variables | ||
| As a reference: when we refer to parameters these are the `$SqlInstance` type variables within the `param()` block that allow a function to accept input. A variable will be any `$whateverName` used within a function's code. | ||
|
|
||
| * **This is how we like people to add new commands** | ||
| <br><br>New command proposals must be approved by Chrissy LeMaire, the original creator of dbatools. This ensures the proposed command aligns with the intended spirit of the toolset. You can message Chrissy on [Slack](https://dbatools.io/slack) (@cl) or post your proposal as a [GitHub Issue](https://dbatools.io/issues).<br><br>Check out the [New Command tag](https://github.com/sqlcollaborative/dbatools/issues?q=is%3Aissue+is%3Aopen+label%3A%22New+Command%22) to get a feel for the types of commands we like. | ||
| We chose to follow the standards below when creating parameters and variables for a function: | ||
|
|
||
| * **Here are some specifics on the coding style we prefer** | ||
| <br><br>This will be available on the Wiki shortly. Until then, please look inside the .ps1 files or the [dbatools-templates](https://github.com/sqlcollaborative/dbatools-templates) repository. | ||
| 1) Any variable used in the parameter block must have first letter of each word capitalized. (e.g. `$SqlInstance`, `$ExcludeLogin`) | ||
| 2) Any variable used in the parameter block **is required** to be singular. | ||
| 3) Any variable not part of the parameter block, that is multiple words, will follow the camelCase format. (e.g. `$currentLogin`, `$dbLogin`) | ||
| 4) Refrain from using single character variable names (e.g. `$i` or `$x`). Try to make them "readable" in the sense that if someone sees the variable name they can get a hint what it presents (e.g. `$db`, `$operatorName`). | ||
|
|
||
| * **This is how you send your pull request** | ||
| <br><br>This information is available on the Wiki as a [step-by-step](https://dbatools.io/firstpull) guide. We even have a [video](https://dbatools.io/firstpullvideo). The most important thing to note is that all pull requests must be made into the **development** branch. We only push to the master branch once a month. | ||
| When you are working with "objects" in SQL Server, say with databases, what variable name you use should be based on what operation you are doing. You can find examples of various situations in the current code of the module to see more detailed examples. As an example: in situations where you are looping over the databases for an instance, try to use a plural variable name for the collection and then single or abbreviated name in the loop for each object of that collection. e.g. `foreach ($db in $databases) {...`. | ||
|
|
||
| * **You should include the following documentation** | ||
| <br><br>Please look at the available [dbatools-templates](https://github.com/sqlcollaborative/dbatools-templates) to see the kind of documentation we're looking for (basically everything that PowerShell allows - SYNOPSIS, DESCRIPTION, PARAMETERS, NOTES, EXAMPLES, and so on. | ||
|
|
||
| * **You should include the following tests** | ||
| <br><br>Please include at least 3 Examples in your command's documentation section. We use these to perform our tests. You can also look at [this awesome Pull Request comment](https://github.com/sqlcollaborative/dbatools/pull/254#issuecomment-253355070) that has step-by-step tests and expected outcomes for our QA team. | ||
| If you have any questions around the above do not hesitate to ask in Slack. | ||
|
|
||
| # Bug triage | ||
| ## Tests | ||
| Remember that tests are needed to make sure dbatools code behaves properly. The ultimate goal is for any user to be able to run dbatools' tests within their environment and, depending on the result, be sure everything works as expected. Dbatools works on a matrix of environments that will hardly be fully covered by a Continuous Integration system. That being said, we have AppVeyor (see later) set up to run at each and every commit. | ||
|
|
||
| This sections explains how bug triaging is done for our project. | ||
| ### How to write tests | ||
| To save resources and be more flexible, we split tests with tags into two main categories, "UnitTests" and "IntegrationTests". Below is a starting list of things to consider when writing your test: | ||
| - "UnitTests" do not require an instance to be up and running, and are easily the most flexible to be ran on every user computer. - "IntegrationTests" instead require one or more active instances, and there is a bit of setup to do in order to run them. | ||
| - Every one of the "IntegrationTests" may need to create a resource (e.g. a database). | ||
| - Every resource should be named with the "dbatoolsci_" prefix. _The test should attempt to clean up after itself leaving a pristine environment._ | ||
| - Try to write tests thinking they may run in each and every user's test environment. | ||
|
|
||
| * You can help report bugs by filing them on our [GitHub Issues page](https://github.com/sqlcollaborative/dbatools/issues) | ||
| * You can look through the existing bugs on our [GitHub Issues page](https://github.com/sqlcollaborative/dbatools/issues) | ||
| * You can help us diagnose and fix existing bugs by asking and providing answers for the following: | ||
| * Is the bug reproducible as explained? | ||
| * Is it reproducible in other environments (for instance, on different browsers or devices)? | ||
| * Are the steps to reproduce the bug clear? If not, can you describe how you might reproduce it? | ||
| * What tags should the bug have? | ||
| * Is this bug something you have run into? Would you appreciate it being looked into faster? | ||
| The dbatools-templates repository holds examples, but you can also inspect/copy/cannibalize existing tests. You'll see that every test file is named with a simple convention _Verb-Noun*.Tests.ps1_, and this is required by [Pester](https://GitHub.com/pester/Pester), which is the de-facto standard for running tests in PowerShell. | ||
|
|
||
| # Beta testing | ||
| Tests make sure a "contract" is made between the code and its behavior: once a test is formalized, changes to the code itself or enhancement will be written making sure existing functionality is retained, making the entire dbatools experience more stable. | ||
|
|
||
| Early releases require heavy testing and how they can help with specially across different versions, editions, and environments. | ||
| TODO: how to run tests in your environment, tests\manual.pester.ps1 | ||
|
|
||
| # Translations | ||
| ### AppVeyor setup | ||
|
|
||
| * You can help us translate our project by submitting a PR with the translation. We hope to add localization to the project by version 2.0 | ||
| AppVeyor is hooked up to test any commit, including PRs. Each commit triggers 4 builds, each referred to as a "scenario": | ||
| - 2008R2 : a server with a single SQL Server 2008 R2 Express Edition instance available ($script:instance1) | ||
| - 2016 : a server with a single SQL Server 2016 Developer Edition instance available ($script:instance2) | ||
| - 2016_service: used to test service restarts | ||
| - default: a server with two instances available, one SQL Server 2008 R2 Express Edition and a SQL Server 2016 Developer Edition | ||
|
|
||
| # Documentation | ||
| Builds are split among "scenario"(s) because not every test requires everything to be up and running, and resources on AppVeyor are constrained. | ||
|
|
||
| Code needs explanation, and sometimes those who know the code well have trouble explaining it to someone just getting into it. | ||
| Ideally: | ||
| 1) Whenever possible, write UnitTests. | ||
| 2) You should write IntegrationTests ideally running in **EITHER** the 2008R2 or the 2016 "scenario". | ||
| 3) Default is the most resource constrained and is left to run the Copy-* commands; which are the only ones **needing** two active instances. | ||
| 4) If you want to write tests that target **BOTH** 2008R2 and 2016, try to avoid writing tests that need both instances to be active at the same time. | ||
|
|
||
| * Help us with documentation by modifying the command's Help section and submitting a Pull Request. You can also message @cl on Slack with modifications for the [documentation on the dbatools website](https://dbatools.io/commands). | ||
| AppVeyor is set up to recognize what "scenario" is required by your test, simply inspecting for the presence of "$script:instance1" and/or "$script:instance2". If you need to fall into case (4), write two test files, e.g. _Get-DbaFoo.first.Tests.ps1 (targeting $script:instance1 only) and _Get-DbaFoo.second.Tests.ps1_ (targeting $script:instance2 only). If you don't want to wait for the entire test suite to run (i.e. you need to run only Get-DbaFoo on AppVeyor), you can use a "magic command" within the commit message, namely `(do Get-DbaFoo)` . This will run only test files within the test folder matching this mask `tests\*Get-DbaFoo*.Tests.ps1`. | ||
|
|
||
| # Community | ||
| This section includes ideas on how non-developers can help with the project. | ||
| TODO: how to run your own AppVeyor before pushing a PR | ||
|
|
||
| * You can help us answer questions our users have on [Slack](https://dbatools.io/slack) | ||
| * You can help design the commands so that they solve your problems in a [Github Issue](https://github.com/sqlcollaborative/dbatools/issues) | ||
| * You can help write blog posts about dbatools | ||
| * You can help create videos and we'll put them on our [YouTube channel](https://dbatools.io/youtube) | ||
| ### Code Coverage, AKA improving tests | ||
| A recent introduction in our CI pipeline is code coverage. [Dbatools' CodeCov](https://codecov.io/gh/sqlcollaborative/dbatools/branch/development) shows the percentage of the coverage. Each commit on GitHub triggers a build on AppVeyor. Every build on AppVeyor triggers a code coverage calculation, which is reported to codecov.io for public consumption. The more code covered the more stable the code will be. Once it reaches 100%, you can be pretty sure there will be zero surprises when you'll use the command. | ||
|
|
||
| If you want to start contributing new tests, choose the ones with no coverage. You can also inspect functions with low coverage and improve existing tests (https://dbatools.io/improving-tests/) | ||
|
|
||
| TODO: rewrite manual.pester.ps1 to show coverage, too | ||
|
|
||
|
|
||
| ## Bill of Health | ||
|
|
||
| In order to reach 1.0, on top of everything discussed above, we choose to wait for each and every command to adhere to a fixed set of standards. Given most of those "checks" are on a function-by-function basis (with one or more activities tied to each "check"), we came up with the "Bill of Health". You can find it bill at [sqlcollaborative.github.io/boh](https://sqlcollaborative.github.io/boh). | ||
|
|
||
| When each and every function is healthy enough, the module itself will be ready for 1.0 release. We may continue to use the same approach (with different checks) for later releases. | ||
|
|
||
| There are a few checks which need a core developer to manually sign off the "check", but there are a lot everyone else can fix too, namely ScriptAnalyzer and CodeCoverage. | ||
|
|
||
| TODO: copy documentation for manually signing off checks from https://GitHub.com/sqlcollaborative/dbatools-progressmanagement |