percona/percona-toolkit
1
0
Fork 0
mirror of https://github.com/percona/percona-toolkit.git synced 2025-10-19 17:04:00 +00:00
Code Issues Packages Projects Releases Wiki Activity

PT-2029 update contributing.md (#534)

Browse Source 
* Work on PT-2029 started

* PT-2029: Polished Perl and Bash related instructions in CONTRIBUTE.md

* PT-2029: restructure for CONTRIBUTE.md

* PT-2029: more structure changes for CONTRIBUTE.md

* PT-2029 - added Go content to CONTRIBUTE.md and removed from README.md,
reorganized CONTRIBUTE.md: removed duplicate content, added Go and documentation related stuff
This commit is contained in:
Sveta Smirnova
2022-03-22 16:24:37 +03:00
committed by GitHub
parent 22ed941238
commit 2760e8c927
2 changed files with 190 additions and 167 deletions
Download Patch File Download Diff File Expand all files Collapse all files

339
CONTRIBUTE.md
View File

@@ -1,149 +1,190 @@
# Contributing guide # Contributing Guide
## How Can I Contribute? ## How Can I Contribute?
## Reporting Bugs ## Reporting Bugs
Before creating bug reports, please check this list as you might find out that you don't need to create one. When you create a bug report, please include as many details as possible. You can use this template to structure the information. Before creating bug reports, please check [this list](https://jira.percona.com/projects/PT/issues) as you might find out that you don't need to create one. When you create a bug report, please include as many details as possible. You can use [this guide](https://www.percona.com/blog/2019/06/12/report-bugs-improvements-new-feature-requests-for-percona-products/) to structure the information.
### Before Submitting A Bug Report ### Before Submitting a Bug Report
- Ensure you have carefully read the documentation. Percona Toolkit is a mature project with many settings that covers a wide range options. - Ensure you have carefully read the documentation. Percona Toolkit is a mature project with many settings that cover a wide range of options.
- Search for existing bugs in Launchpad to see if the problem has already been reported. If it has, add a comment to the existing issue instead of opening a new one. - Search for existing bugs in [Jira](https://jira.percona.com) to see if the problem has already been reported. If it has, add a comment to the existing issue instead of opening a new one.
By doing this, we can avoid duplicating efforts, since the issue might have been already reported and if not, you might find useful information on older issues related to the same problem.
### How Do I Submit A (Good) Bug Report?
- Explain the problem and include additional details to help others reproduce the problem: ### How Do I Submit a (Good) Bug Report?
- Use a clear and descriptive title for the issue to identify the problem. - Explain the problem and include additional details to help others to reproduce the problem.
- Describe the exact steps which reproduce the problem, including as many details as possible. Provide examples of the command you used and include context information like language, OS and database versions. - Use a clear and descriptive title for the issue.
Describe the obtained results and the expected results and, if it is possible, provide examples. - Be clear about what your problem is: which program you are using, what is the expected result and what is the result you are getting.
- Include system details, such as language version, OS, database details or special configurations, etc.
## Submiting fixes - Describe the exact steps which reproduce the problem, including as many details as possible. Provide examples of the command you used and include context information like language, OS and database versions.
### Create an Issue - Describe the obtained and the expected results and, if possible, provide examples.
If you find a bug, the first step is to create an issue. Whatever the problem is, you’re likely not the only one experiencing it. Others will find your issue helpful, and other developers might help you find the cause and discuss the best solution for it. - Paste the error output or logs into Jira issue or attach them. You may put large files on our SFTP server if needed. Use Jira issue number as a login and password for the [Percona SFTP server](sftp.percona.com). Have Jira issue number in the file name and add a comment, so we can access it.
#### Tips for creating an issue ## Reporting Documentation Issues
- Check if there are any existing issues for your problem. By doing this, we can avoid duplicating efforts, since the issue might have been already reported and if not, you might find useful information on older issues related to the same problem. Documentation bugs for Percona Toolkit should be reported at [Percona Jira](https://jira.percona.com/) in the project **PT** and have component **Documentation**.
- Be clear about what your problem is: which program were you using, what was the expected result and what is the result you are getting. Detail how someone else can reproduce the problem, including examples.
- Include system details like language version, OS, database details or special configurations, etc. ### Good Documentation Bug Report
- Paste the error output or logs in your issue or in a Gist. - Contains link to the user manual page where the documentation is wrong
- Fully explains the problem
### Pull Requests - Optionally explains how documentation should be fixed
If you fixed a bug or added a new feature – awesome! Open a pull request with the code! Be sure you’ve read any documents on contributing, understand the license and have signed a Contributor Licence Agreement (CLA) if required. Once you’ve submitted a pull request, the maintainers can compare your branch to the existing one and decide whether or not to incorporate (merge) your changes.
## Introducing Changes to the Toolkit
### Tips for creating a pull request ### Set Up the Source Code
- Fork the repository and clone it locally. Connect your local to the original ‘upstream’ repository by adding it as a remote. Pull in changes from ‘upstream’ often so that you stay up to date so that when you submit your pull request, merge conflicts will be less likely. To start, fork the Percona Toolkit repo to be able to submit pull requests and clone it locally:
- Create a branch for your code. Usually it is a good practice to name the branch after the issue ID, like issue-12345. ```
- Be clear about the problem you fixed or the feature you added. Include explanations and code references to help the maintainers understand what you did. mkdir ${HOME}/perldev
- Add useful comments to the code to help others understand it. git clone https://github.com/percona/percona-toolkit.git ${HOME}/perldev/percona-toolkit
- Write tests. This is an important step. Run your changes against existing tests and create new ones when needed. Whether tests exist or not, make sure your changes don’t break the existing project. ```
- Contribute in the style of the project to the best of your abilities. This may mean using indents, semicolons, or comments differently than you would in your own repository, but makes it easier for the maintainer to merge, others to understand and maintain in the future. ### Create a New Branch
- Keep your changes as small as possible and solve only what's reported in the issue. Mixing fixes might be confusing to others and makes testing harder.
- Be as explicit as possible. Avoid using special/internal language variables like $_. Use a variable name that clearly represents the value it holds. You should start your own development branch. If you have a Jira ticket assigned, use its number as a reference, and add a short description of what work on this branch will do:
- Write good commit messages. A comment like 'Misc bugfixes' or 'More code added' does not help to understand what's the change about. ```
git checkout -b PT-9999_functionality_name
### Open Pull Requests ```
Once you’ve opened a pull request, a discussion will start around your proposed changes. Other contributors and users may chime in, but ultimately the decision is made by the maintainers. You may be asked to make some changes to your pull request, if so, add more commits to your branch and push them – they’ll automatically go into the existing pull request. The first commit should also have the Jira reference number as first characters in the commit message (so that Jiraf can use the smart tags).
# Licensing ### Example Commit Message
Along with the pull request, include a message indicating that the submited code is your own creation and it can be distributed under the BSD licence.
```
PT-12345 - fixed data corruption issue for pt-foo
# Setting up the development environment
New check pt-foo-test-env added when pt-foo is going to perform destructive operation.
#### Setting up the source code If check fails, now pt-foo will stop executing and return an error.
To start, fork the Percona Toolkit repo to be able to submit pull requests and clone it locally: ```
```
mkdir ${HOME}/perldev ### Changing Shared Code
git clone https://github.com/<your-username>/percona-toolkit.git ${HOME}/perldev/percona-toolkit
``` Percona Toolkit uses `lib` directory for library code. Once you change it you need to run the `update-modules` tool that will merge module code with the tools. Be careful and **do not modify** anything between the `This package is a copy without comments from the original` and `End ... package` comments.
For testing, we are going to need to have MySQL with slaves. For that, we already have scripts in the sandbox directory but first we need to download MySQL binaries. Please download the Linux Generic tar file for your distrubution from [https://www.percona.com/downloads/Percona-Server-5.6/](https://www.percona.com/downloads/Percona-Server-5.6/). ### Running the update-modules Tool
### Set up MySQL sandbox Whenever you make changes to libraries under `lib/`, you should make sure that you run the `util/update-modules` functionality, to make sure that all tools that use these packages will benefit from the new changes. For example, let's say you changed the `lib/bash/collect.sh` package, you will need to run:
In this example, we are going to download Percona Server 5.6.32. Since I am using Ubuntu, according to the documentation [here](https://www.percona.com/doc/percona-server/5.6/installation.html#installing-percona-server-from-a-binary-tarball), I am going to need this tar file: [Percona-Server-5.6.32-rel78.1-Linux.x86_64.ssl100.tar.gz](https://www.percona.com/downloads/Percona-Server-5.6/Percona-Server-5.6.32-78.1/binary/tarball/Percona-Server-5.6.32-rel78.1-Linux.x86_64.ssl100.tar.gz). ```
cd ${HOME}/perldev/percona-toolkit
``` for t in bin/*; do util/update-modules ${t} collect; done
mkdir -p ${HOME}/mysql/percona-server-5.6.32 ```
``` Or if you changed the `lib/NibbleIterator.pm` package:
``` ```
wget https://www.percona.com/downloads/Percona-Server-5.6/Percona-Server-5.6.32-78.1/binary/tarball/Percona-Server-5.6.32-rel78.1-Linux.x86_64.ssl100.tar.gz cd ${HOME}/perldev/percona-toolkit
``` for t in bin/*; do util/update-modules ${t} NibbleIterator; done
``` ```
tar xvzf Percona-Server-5.6.32-rel78.1-Linux.x86_64.ssl100.tar.gz --strip 1 -C ${HOME}/mysql/percona-server-5.6.32
``` ## Uploading Your Branch
### Set up environment variables
We need these environment variables to start the MySQL sandbox and to run the tests. Probably it is a good idea to add them to your `.bashrc` file. Finally, after you run another round of tests and everything is OK, you should upload your branch to your GitHub fork:
``` ```
export PERCONA_TOOLKIT_BRANCH=${HOME}/perldev/percona-toolkit git push origin PT-9999_functionality_name
export PERL5LIB=${HOME}/perldev/percona-toolkit/lib ```
export PERCONA_TOOLKIT_SANDBOX=${HOME}/mysql/percona-server-5.6.32 And then go to the web UI to create the new pull request (PR) based off of this new branch.
```
## Submiting Fixes
### Check that all needed tools are correctly installed: ### Pull Requests
``` Once your fix is ready and you pushed it into the feature branch, open a pull request with the code. Be sure you’ve read any documents on contributing, understand the license and have signed a [Contributor Licence Agreement (CLA)](https://github.com/percona/percona-toolkit/blob/3.x/CONTRIBUTING.md). Once you’ve submitted a pull request, the maintainers can compare your branch to the existing one and decide whether or not to incorporate (merge) your changes.
util/check-dev-env
``` ### Tips for Creating a Pull Request
If not, you will have to either install them via your package manager of preference, or using Perl directly. For example, let's assume that you are missing the `File::Slurp` package (as flagged by a `NA` output from the previous command), you can use: - Be clear about the problem you fixed or the feature you added. Include explanations and code references to help the maintainers understand what you did.
``` - Add useful comments to the code to help others understand it.
sudo perl -MCPAN -e "shell" - Write tests. This is an important step. Run your changes against existing tests and create new ones when needed. Whether tests exist or not, make sure your changes don’t break the existing project.
cpan[1]> install File::Slurp - Contribute in the style of the project to the best of your abilities. This may mean using indents, semicolons, or comments differently than you would in your own repository, but makes it easier for the maintainer to merge, others to understand and maintain in the future.
... - Keep your changes as small as possible and solve only what's reported in the issue. Mixing fixes might be confusing to others and makes testing harder.
``` - Be as explicit as possible. Avoid using special/internal language variables like `$_`. Use a variable name that clearly represents the value it holds.
- Write good commit messages. A comment like *'Misc bugfixes'* or *'More code added'* does not help to understand what's the change about.
### Starting the sandbox - Put Jira issue number into the commit message to automatically link it with the Jira issue.
```
cd ${HOME}/perldev/percona-toolkit ### Open a Pull Request
``` Once you’ve opened a pull request, a discussion will start around your proposed changes. Other contributors and users may chime in, but ultimately the decision is made by the maintainers. You may be asked to make some changes to your pull request, if so, add more commits to your branch and push them – they’ll automatically go into the existing pull request.
```
sandbox/test-env start ## Licensing
``` Along with the pull request, include a message indicating that the submited code is your own creation and it can be distributed under the GPL2 licence.
To stop the MySQL sandbox: `sandbox/test-env stop`
To enable TokuDB (only available in Percona Server 5.7+), run:
## Setting up the Development Environment and Testing
``` ### Perl and Shell Tools
ENABLE_TOKUDB=1 sandbox/test-env start For testing, we are going to need to have MySQL with replicas. For that, we already have scripts in the sandbox directory but first we need to download MySQL binaries. Please download the Linux Generic tar file for your distrubution from [https://www.percona.com/downloads/Percona-Server-LATEST/](https://www.percona.com/downloads/Percona-Server-LATEST/).
```
#### Set up MySQL Sandbox
### Running tests In this example, we are going to download Percona Server 8.0.26-17.
```
cd ${HOME}/perldev/percona-toolkit ```
``` mkdir -p ${HOME}/mysql/percona-server-8.0.26-17
Run all tests for a particular program (pt-stalk in this example): ```
``` ```
prove -v t/pt-stalk/ wget https://downloads.percona.com/downloads/Percona-Server-LATEST/Percona-Server-8.0.26-17/binary/tarball/Percona-Server-8.0.26-17-Linux.x86_64.glibc2.17.tar.gz
``` ```
You can also add warnings with: ```
``` tar xvzf Percona-Server-8.0.26-17-Linux.x86_64.glibc2.17.tar.gz --strip 1 -C ${HOME}/mysql/percona-server-8.0.26-17
prove -vw t/pt-stalk/ ```
``` #### Set Up Environment Variables
or run a specific test: We need these environment variables to start the MySQL sandbox and to run the tests. Probably it is a good idea to add them to your `.bashrc` file.
``` ```
prove -v t/pt-stalk/option_sanity.t export PERCONA_TOOLKIT_BRANCH=${HOME}/perldev/percona-toolkit
``` export PERL5LIB=${HOME}/perldev/percona-toolkit/lib
export PERCONA_TOOLKIT_SANDBOX=${HOME}/mysql/percona-server-8.0.26-17
# Introducing changes to the toolkit ```
## Creating a new branch #### Check That All Needed Tools Are Correctly Installed:
```
You should start your own development branch. If you have a JIRA ticket assigned, use its number as reference, and add a short description of what work on this branch will do: util/check-dev-env
``` ```
git checkout -b PT-9999_functionality_name If not, you will have to either install them via your package manager of preference, or using Perl directly. For example, let's assume that you are missing the `File::Slurp` package (as flagged by a `NA` output from the previous command), you can use:
``` ```
The first commit should also have the JIRA reference number as first characters in the commit message (so that JIRA can use the smart tags). sudo perl -MCPAN -e "shell"
cpan[1]> install File::Slurp
## Running the update-modules tool ...
```
Whenever you make changes to libraries under lib/, you should make sure that you run the util/update-modules functionality, to make sure that all tools that use these packages will benefit from the new changes. For example, let's say you changed the lib/bash/collect.sh package, you will need to run:
``` #### Starting the Sandbox
cd ${HOME}/perldev/percona-toolkit ```
for t in bin/*; do util/update-modules ${t} collect; done cd ${HOME}/perldev/percona-toolkit
``` ```
Or if you changed the lib/NibbleIterator.pm package: ```
``` sandbox/test-env start
cd ${HOME}/perldev/percona-toolkit ```
for t in bin/*; do util/update-modules ${t} NibbleIterator; done To stop the MySQL sandbox: `sandbox/test-env stop`
``` To enable TokuDB (only available in Percona Server 5.7+), run:
## Uploading your branch ```
ENABLE_TOKUDB=1 sandbox/test-env start
Finally, after you run another round of tests and everything is ok, you should upload your branch to your GitHub fork: ```
```
git push origin PT-9999_functionality_name To enable MyRocks (only available in Percona Server 5.7+), run:
```
And then go to the web UI to create the new pull request (PR) based off of this new branch. ```
ENABLE_ROCKSDB=1 sandbox/test-env start
```
#### Running Tests
```
cd ${HOME}/perldev/percona-toolkit
```
Run all tests for a particular program (pt-stalk in this example):
```
prove -v t/pt-stalk/
```
You can also add warnings with:
```
prove -vw t/pt-stalk/
```
or run a specific test:
```
prove -v t/pt-stalk/option_sanity.t
```
### Go Tools
Starting from version 3, there are new tools for MongoDB, written in Go language.
To test these tools, first switch to the `src/go` directory, then use command `make`.
#### Starting the Sandbox
Run command `make env-up`. This will start MongoDB container cluster
#### Build Mongo Tools
Run command `make` with your environment as a parameter. For example, `make linux-amd64` will build Mongo tools for Linux AMD64 platform.
#### Running Tests
Run `make test`
#### Stopping the Sandbox
Run `make env-down`

18
README.md
View File

@@ -33,21 +33,3 @@ are installed in /usr/local/bin. See the INSTALL file for more information.
Run `man percona-toolkit` to see a list of installed tools, then `man tool` Run `man percona-toolkit` to see a list of installed tools, then `man tool`
to read the embedded documentation for a specific tool. You can also read to read the embedded documentation for a specific tool. You can also read
the documentation online at [http://www.percona.com/software/percona-toolkit/](http://www.percona.com/software/percona-toolkit/). the documentation online at [http://www.percona.com/software/percona-toolkit/](http://www.percona.com/software/percona-toolkit/).
## Version 3
Starting from version 3, there are new tools for MongoDB. These tools are written in Go so
in order to compile these program, this repo must me cloned into the GOPATH directory.
Example:
```
mkdir ${HOME}/go
export GOPATH=${HOME}/go
mkdir -p ${HOME}/go/src/github.com/percona
cd ${HOME}/go/src/github.com/percona
git clone https://github.com/percona/percona-toolkit.git
cd percona-toolkit/src/go
make
```