mirror of
https://github.com/pgbackrest/pgbackrest.git
synced 2024-12-12 10:04:14 +02:00
Update contributing documentation and add pull request template.
This commit is contained in:
Cynthia Shang
GitHub
parent
46992acd80
commit
e3d05e2b4a
1
.github/pull_request_template.md
vendored
Normal file
1
.github/pull_request_template.md
vendored
Normal file
@ -0,0 +1 @@
|
||||
Please read [Submitting a Pull Request](https://github.com/pgbackrest/pgbackrest/blob/master/CONTRIBUTING.md#submitting-a-pull-request) before submitting.
|
||||
@ -1,5 +1,17 @@
|
||||
# pgBackRest <br/> Contributing to pgBackRest
|
||||
|
||||
## Table of Contents
|
||||
|
||||
[Introduction](#introduction)
|
||||
|
||||
[Building a Development Environment](#building-a-development-environment)
|
||||
|
||||
[Coding](#coding)
|
||||
|
||||
[Testing](#testing)
|
||||
|
||||
[Submitting a Pull Request](#submitting-a-pull-request)
|
||||
|
||||
## Introduction
|
||||
|
||||
This documentation is intended to assist contributors to pgBackRest by outlining some basic steps and guidelines for contributing to the project.
|
||||
@ -10,7 +22,7 @@ Bug reports should be [submitted as issues](https://github.com/pgbackrest/pgback
|
||||
|
||||
You will always receive credit in the [release notes](http://www.pgbackrest.org/release.html) for your contributions.
|
||||
|
||||
Coding standards are defined in [CODING.md](https://github.com/pgbackrest/pgbackrest/blob/master/CODING.md) and some important coding details and an example are provided in the [Coding](#coding) section below. At a minimum, unit tests must be written and run and the documentation generated before submitting a Pull Request; see the [Testing](#testing) section below for details.
|
||||
Coding standards are defined in [CODING.md](https://github.com/pgbackrest/pgbackrest/blob/master/CODING.md) and some important coding details and an example are provided in the [Coding](#coding) section below. At a minimum, unit tests must be written and run and the documentation generated before [submitting a Pull Request](#submitting-a-pull-request); see the [Testing](#testing) section below for details.
|
||||
|
||||
## Building a Development Environment
|
||||
|
||||
@ -211,7 +223,7 @@ Examples of test runs are provided in the following sections. There are several
|
||||
|
||||
- `--vm-out` - displays the test output (helpful for monitoring the progress)
|
||||
|
||||
- `--vm` - identifies the pre-built container when using Docker, otherwise the setting should be `none`
|
||||
- `--vm` - identifies the pre-built container when using Docker, otherwise the setting should be `none`. See [test.yml](https://github.com/pgbackrest/pgbackrest/blob/master.github/workflows/test.yml) for a list of valid vm codes noted by `param: test`.
|
||||
|
||||
For more options, run the test or documentation engine with the `--help` option:
|
||||
```
|
||||
@ -229,7 +241,7 @@ pgbackrest/test/test.pl --vm=none --dry-run
|
||||
|
||||
--- output ---
|
||||
|
||||
P00 INFO: test begin on aarch64 - log level info
|
||||
P00 INFO: test begin on x86_64 - log level info
|
||||
P00 INFO: configure build
|
||||
P00 INFO: builds required: bin
|
||||
--> P00 INFO: 72 tests selected
|
||||
@ -247,7 +259,7 @@ pgbackrest/test/test.pl --vm=none --vm-out --module=common --test=wait
|
||||
|
||||
--- output ---
|
||||
|
||||
P00 INFO: test begin on aarch64 - log level info
|
||||
P00 INFO: test begin on x86_64 - log level info
|
||||
P00 INFO: autogenerate configure
|
||||
P00 INFO: autogenerated version in configure.ac script: no changes
|
||||
P00 INFO: autogenerated configure script: no changes
|
||||
@ -303,7 +315,7 @@ pgbackrest/test/test.pl --vm=none --module=postgres
|
||||
|
||||
--- output ---
|
||||
|
||||
P00 INFO: test begin on aarch64 - log level info
|
||||
P00 INFO: test begin on x86_64 - log level info
|
||||
P00 INFO: autogenerate configure
|
||||
P00 INFO: autogenerated version in configure.ac script: no changes
|
||||
P00 INFO: autogenerated configure script: no changes
|
||||
@ -330,8 +342,8 @@ pgbackrest/test/test.pl --vm-build --vm=u20
|
||||
|
||||
--- output ---
|
||||
|
||||
P00 INFO: test begin on aarch64 - log level info
|
||||
P00 INFO: Using cached pgbackrest/test:u20-base-20210718A image (d6c377617ac2c112b80a3c1f090345d54769ae1b) ...
|
||||
P00 INFO: test begin on x86_64 - log level info
|
||||
P00 INFO: Using cached pgbackrest/test:u20-base-20210717A image (d6c377617ac2c112b80a3c1f090345d54769ae1b) ...
|
||||
P00 INFO: Building pgbackrest/test:u20-test image ...
|
||||
P00 INFO: Build Complete
|
||||
```
|
||||
@ -343,7 +355,7 @@ pgbackrest/test/test.pl --vm=u20 --module=mock --test=archive --run=2
|
||||
|
||||
--- output ---
|
||||
|
||||
P00 INFO: test begin on aarch64 - log level info
|
||||
P00 INFO: test begin on x86_64 - log level info
|
||||
P00 INFO: autogenerate configure
|
||||
P00 INFO: autogenerated version in configure.ac script: no changes
|
||||
P00 INFO: autogenerated configure script: no changes
|
||||
@ -351,9 +363,9 @@ pgbackrest/test/test.pl --vm=u20 --module=mock --test=archive --run=2
|
||||
P00 INFO: autogenerated C code: no changes
|
||||
P00 INFO: cleanup old data and containers
|
||||
P00 INFO: builds required: bin, bin host
|
||||
P00 INFO: build bin for u20 (/home/docker/test/bin/u20)
|
||||
P00 INFO: build bin for u20 (/home/vagrant/test/bin/u20)
|
||||
P00 INFO: bin dependencies have changed, rebuilding
|
||||
P00 INFO: build bin for none (/home/docker/test/bin/none)
|
||||
P00 INFO: build bin for none (/home/vagrant/test/bin/none)
|
||||
P00 INFO: bin dependencies have changed, rebuilding
|
||||
P00 INFO: 1 test selected
|
||||
|
||||
@ -397,7 +409,7 @@ Assuming that a test file already exists, new unit tests will either go in a new
|
||||
// *****************************************************************************************************************************
|
||||
if (testBegin("expireBackup()"))
|
||||
{
|
||||
//--------------------------------------------------------------------------------------------------------------------------
|
||||
// -------------------------------------------------------------------------------------------------------------------------
|
||||
TEST_TITLE("manifest file removal");
|
||||
```
|
||||
|
||||
@ -436,6 +448,7 @@ Tests are run and results confirmed via macros that are described in [harnessTes
|
||||
- `TEST_RESULT_VOID` - The function being tested returns a `void`. This is then usually followed by tests that ensure other actions occurred (e.g. a file was written to disk).
|
||||
|
||||
- `TEST_ERROR` / `TEST_ERROR_FMT` - Test that a specific error code was raised with specific wording.
|
||||
> **NOTE:** `HRN_*` macros should be used only for test setup and cleanup. `TEST_*` macros must be used for testing results.
|
||||
|
||||
#### Testing a log message
|
||||
|
||||
@ -444,6 +457,7 @@ If a function being tested logs something with `LOG_WARN`, `LOG_INFO` or other `
|
||||
TEST_RESULT_LOG(
|
||||
"P00 WARN: WAL segment '000000010000000100000001' was not pushed due to error [25] and was manually skipped: error");
|
||||
```
|
||||
In the above, `Pxx` indicates the process (P) and the process number (xx), e.g. P00, P01.
|
||||
|
||||
#### Testing using child process
|
||||
|
||||
@ -524,6 +538,24 @@ Sometimes it is useful to look at files that were generated during the test. The
|
||||
pgbackrest/test/test.pl --vm-out --module=command --test=check --run=1 --no-cleanup
|
||||
```
|
||||
|
||||
### Understanding Test Output
|
||||
|
||||
The following is a small sample of a typical test output.
|
||||
```
|
||||
run 8 - expireTimeBasedBackup()
|
||||
|
||||
run 8/1 ------------- L2285 no current backups
|
||||
000.002s L2298 empty backup.info
|
||||
000.009s 000.007s L2300 no backups to expire
|
||||
```
|
||||
**run 8 - expireTimeBasedBackup()** - indicates the run number (8) within the module and the parameter provided to testBegin, e.g. `testBegin("expireTimeBasedBackup()")`
|
||||
|
||||
**run 8/1 ------------- L2285 no current backups** - this is the first test (1) in run 8 which is the `TEST_TITLE("no current backups");` at line number 2285.
|
||||
|
||||
**000.002s L2298 empty backup.info** - the first number, 000.002s, is the time in seconds that the test started from the beginning of the run. L2298 is the line number of the test and `empty backup.info` is the test comment.
|
||||
|
||||
**000.009s 000.007s L2300 no backups to expire** - again, 000.009s, is the time in seconds that the test started from the beginning of the run. The second number, 000.007s, is the run time of the **previous** test (i.e. `empty backup.info` test took 000.007 seconds to execute). L2300 is the line number of the test and `no backups to expire` is the test comment.
|
||||
|
||||
## Adding an Option
|
||||
|
||||
Options can be added to a command or multiple commands. Options can be configuration file only, command-line only or valid for both. Once an option is successfully added, `config.auto.*`, `define.auto.*` and `parse.auto.*` files will automatically be generated by the build system.
|
||||
@ -658,10 +690,44 @@ pgbackrest/doc/doc.pl --output=html --no-exe
|
||||
```
|
||||
The generated HTML files will be placed in the `doc/output/html` directory where they can be viewed locally in a browser.
|
||||
|
||||
If Docker is installed, it will be used by the documentation generator to execute the code elements while building the documentation. `--no-cache` may be used to force a full build even when no code elements have changed since the last build. `--pre` will reuse the container definitions from the prior build and saves time during development.
|
||||
If Docker is installed, it will be used by the documentation generator to execute the code elements while building the documentation, therefore, the `--no-exe` should be omitted, (i.e. `pgbackrest/doc/doc.pl --output=html`). `--no-cache` may be used to force a full build even when no code elements have changed since the last build. `--pre` will reuse the container definitions from the prior build and saves time during development.
|
||||
|
||||
The containers created for documentation builds can be useful for manually testing or trying out new code or features. The following demonstrates building through just the `quickstart` section of the `user-guide` without encryption.
|
||||
```
|
||||
pgbackrest/doc/doc.pl --out=html --include=user-guide --require=/quickstart --var=encrypt=n --no-cache --pre
|
||||
```
|
||||
The resulting Docker containers can be listed with `docker ps` and the container can be entered with `docker exec doc-pg-primary bash`. Additionally, the `-u` option can be added for entering the container as a specific user (e.g. `postgres`).
|
||||
|
||||
## Submitting a Pull Request
|
||||
|
||||
Before submitting a Pull Request:
|
||||
|
||||
- Does it meet the [coding standards](https://github.com/pgbackrest/pgbackrest/blob/master/CODING.md)?
|
||||
|
||||
|
||||
- Have [Unit Tests](#writing-a-unit-test) been written and [run](#running-a-unit-test) with 100% coverage?
|
||||
|
||||
|
||||
- If your submission includes changes to the help or online documentation, have the [help](#testing-the-help) and [documentation](#testing-the-documentation) tests been run?
|
||||
|
||||
|
||||
- Has it passed continuous integration testing? Simply renaming your branch with the appendix `-cig` and pushing it to your GitHub account will initiate GitHub Actions to run CI tests.
|
||||
|
||||
|
||||
When submitting a Pull Request:
|
||||
|
||||
- Provide a short submission title.
|
||||
|
||||
|
||||
- Write a detailed comment to describe the purpose of your submission and any issue(s), if any, it is resolving; a link to the GitHub issue is also helpful.
|
||||
|
||||
|
||||
After submitting a Pull Request:
|
||||
|
||||
- One or more reviewers will be assigned.
|
||||
|
||||
|
||||
- Respond to any issues (conversations) in GitHub but do not resolve the conversation; the reviewer is responsible for ensuring the issue raised has been resolved and marking the conversation resolved. It is helpful to supply the commit in your reply if one was submitted to fix the issue.
|
||||
|
||||
|
||||
Lastly, thank you for contributing to pgBackRest!
|
||||
|
||||
@ -47,6 +47,16 @@
|
||||
</host-define>
|
||||
|
||||
<!-- ======================================================================================================================= -->
|
||||
<section id="contents">
|
||||
<title>Table of Contents</title>
|
||||
|
||||
<p><link section="/introduction">Introduction</link></p>
|
||||
<p><link section="/environment">Building a Development Environment</link></p>
|
||||
<p><link section="/coding">Coding</link></p>
|
||||
<p><link section="/testing">Testing</link></p>
|
||||
<p><link section="/pr">Submitting a Pull Request</link></p>
|
||||
</section>
|
||||
|
||||
<section id="introduction">
|
||||
<title>Introduction</title>
|
||||
|
||||
@ -58,7 +68,7 @@
|
||||
|
||||
You will always receive credit in the <link page="{[backrest-page-release]}">release notes</link> for your contributions.
|
||||
|
||||
Coding standards are defined in <link url="{[github-url-master]}/CODING.md">CODING.md</link> and some important coding details and an example are provided in the <link section="/coding">Coding</link> section below. At a minimum, unit tests must be written and run and the documentation generated before submitting a Pull Request; see the <link section="/testing">Testing</link> section below for details.</p>
|
||||
Coding standards are defined in <link url="{[github-url-master]}/CODING.md">CODING.md</link> and some important coding details and an example are provided in the <link section="/coding">Coding</link> section below. At a minimum, unit tests must be written and run and the documentation generated before <link section="/pr">submitting a Pull Request</link>; see the <link section="/testing">Testing</link> section below for details.</p>
|
||||
</section>
|
||||
|
||||
<!-- ======================================================================================================================= -->
|
||||
@ -318,7 +328,7 @@ myObjToLog(const MyObj *this)
|
||||
<list-item><setting>--test</setting> - the actual test set to be run</list-item>
|
||||
<list-item><setting>--run</setting> - a number identifying the run within a test if testing a single run rather than the entire test</list-item>
|
||||
<list-item><setting>--vm-out</setting> - displays the test output (helpful for monitoring the progress)</list-item>
|
||||
<list-item><setting>--vm</setting> - identifies the pre-built container when using Docker, otherwise the setting should be <code>none</code></list-item>
|
||||
<list-item><setting>--vm</setting> - identifies the pre-built container when using Docker, otherwise the setting should be <code>none</code>. See <link url="{[github-url-master]}.github/workflows/test.yml">test.yml</link> for a list of valid vm codes noted by <code>param: test</code>.</list-item>
|
||||
</list>
|
||||
|
||||
<p>For more options, run the test or documentation engine with the <setting>--help</setting> option:</p>
|
||||
@ -433,7 +443,7 @@ pgbackrest/doc/doc.pl --help
|
||||
// *****************************************************************************************************************************
|
||||
if (testBegin("expireBackup()"))
|
||||
{
|
||||
//--------------------------------------------------------------------------------------------------------------------------
|
||||
// -------------------------------------------------------------------------------------------------------------------------
|
||||
TEST_TITLE("manifest file removal");
|
||||
</code-block>
|
||||
</section>
|
||||
@ -477,6 +487,8 @@ HRN_STORAGE_PUT_EMPTY(
|
||||
<list-item><id>TEST_RESULT_VOID</id> - The function being tested returns a <code>void</code>. This is then usually followed by tests that ensure other actions occurred (e.g. a file was written to disk).</list-item>
|
||||
<list-item><id>TEST_ERROR</id> / <id>TEST_ERROR_FMT</id> - Test that a specific error code was raised with specific wording.</list-item>
|
||||
</list>
|
||||
|
||||
<admonition type="note"><code>HRN_*</code> macros should be used only for test setup and cleanup. <code>TEST_*</code> macros must be used for testing results.</admonition>
|
||||
</section>
|
||||
|
||||
<section id="test-log">
|
||||
@ -488,6 +500,8 @@ HRN_STORAGE_PUT_EMPTY(
|
||||
TEST_RESULT_LOG(
|
||||
"P00 WARN: WAL segment '000000010000000100000001' was not pushed due to error [25] and was manually skipped: error");
|
||||
</code-block>
|
||||
|
||||
<p>In the above, <code>Pxx</code> indicates the process (P) and the process number (xx), e.g. P00, P01.</p>
|
||||
</section>
|
||||
|
||||
<section id="test-child">
|
||||
@ -579,6 +593,28 @@ pgbackrest/test/test.pl --vm-out --module=command --test=check --vm=u20
|
||||
pgbackrest/test/test.pl --vm-out --module=command --test=check --run=1 --no-cleanup
|
||||
</code-block>
|
||||
</section>
|
||||
|
||||
<section id="test-output">
|
||||
<title>Understanding Test Output</title>
|
||||
|
||||
<p>The following is a small sample of a typical test output.</p>
|
||||
|
||||
<code-block>
|
||||
run 8 - expireTimeBasedBackup()
|
||||
|
||||
run 8/1 ------------- L2285 no current backups
|
||||
000.002s L2298 empty backup.info
|
||||
000.009s 000.007s L2300 no backups to expire
|
||||
</code-block>
|
||||
|
||||
<p><b>run 8 - expireTimeBasedBackup()</b> - indicates the run number (8) within the module and the parameter provided to testBegin, e.g. <code>testBegin("expireTimeBasedBackup()")</code></p>
|
||||
|
||||
<p><b>run 8/1 ------------- L2285 no current backups</b> - this is the first test (1) in run 8 which is the <code>TEST_TITLE("no current backups");</code> at line number 2285.</p>
|
||||
|
||||
<p><b>000.002s L2298 empty backup.info</b> - the first number, 000.002s, is the time in seconds that the test started from the beginning of the run. L2298 is the line number of the test and <code>empty backup.info</code> is the test comment.</p>
|
||||
|
||||
<p><b>000.009s 000.007s L2300 no backups to expire</b> - again, 000.009s, is the time in seconds that the test started from the beginning of the run. The second number, 000.007s, is the run time of the <b>previous</b> test (i.e. <code>empty backup.info</code> test took 000.007 seconds to execute). L2300 is the line number of the test and <code>no backups to expire</code> is the test comment.</p>
|
||||
</section>
|
||||
</section>
|
||||
|
||||
<section id="option">
|
||||
@ -730,7 +766,7 @@ pgbackrest/doc/doc.pl --output=html --no-exe
|
||||
|
||||
<p>The generated HTML files will be placed in the <file>doc/output/html</file> directory where they can be viewed locally in a browser.</p>
|
||||
|
||||
<p>If Docker is installed, it will be used by the documentation generator to execute the code elements while building the documentation. <setting>--no-cache</setting> may be used to force a full build even when no code elements have changed since the last build. <setting>--pre</setting> will reuse the container definitions from the prior build and saves time during development.</p>
|
||||
<p>If Docker is installed, it will be used by the documentation generator to execute the code elements while building the documentation, therefore, the <setting>--no-exe</setting> should be omitted, (i.e. <code>pgbackrest/doc/doc.pl --output=html</code>). <setting>--no-cache</setting> may be used to force a full build even when no code elements have changed since the last build. <setting>--pre</setting> will reuse the container definitions from the prior build and saves time during development.</p>
|
||||
|
||||
<p>The containers created for documentation builds can be useful for manually testing or trying out new code or features. The following demonstrates building through just the <code>quickstart</code> section of the <file>user-guide</file> without encryption.</p>
|
||||
|
||||
@ -741,4 +777,40 @@ pgbackrest/doc/doc.pl --out=html --include=user-guide --require=/quickstart --va
|
||||
<p>The resulting Docker containers can be listed with <code>docker ps</code> and the container can be entered with <code>docker exec doc-pg-primary bash</code>. Additionally, the <code>-u</code> option can be added for entering the container as a specific user (e.g. <code>postgres</code>).</p>
|
||||
</section>
|
||||
</section>
|
||||
|
||||
<section id="pr">
|
||||
<title>Submitting a Pull Request</title>
|
||||
|
||||
<p>Before submitting a Pull Request:</p>
|
||||
|
||||
<list>
|
||||
<list-item>Does it meet the <link url="{[github-url-master]}/CODING.md">coding standards</link>?
|
||||
</list-item>
|
||||
<list-item>Have <link section="/testing/unit-test">Unit Tests</link> been written and <link section="/testing/unit-test-run">run</link> with 100% coverage?
|
||||
</list-item>
|
||||
<list-item>If your submission includes changes to the help or online documentation, have the <link section="/option/help-test">help</link> and <link section="/option/doc-test">documentation</link> tests been run?
|
||||
</list-item>
|
||||
<list-item>Has it passed continuous integration testing? Simply renaming your branch with the appendix <code>-cig</code> and pushing it to your GitHub account will initiate GitHub Actions to run CI tests.
|
||||
</list-item>
|
||||
</list>
|
||||
|
||||
<p>When submitting a Pull Request:</p>
|
||||
<list>
|
||||
<list-item>Provide a short submission title.
|
||||
</list-item>
|
||||
<list-item>Write a detailed comment to describe the purpose of your submission and any issue(s), if any, it is resolving; a link to the GitHub issue is also helpful.
|
||||
</list-item>
|
||||
</list>
|
||||
|
||||
<p>After submitting a Pull Request:</p>
|
||||
|
||||
<list>
|
||||
<list-item>One or more reviewers will be assigned.
|
||||
</list-item>
|
||||
<list-item>Respond to any issues (conversations) in GitHub but do not resolve the conversation; the reviewer is responsible for ensuring the issue raised has been resolved and marking the conversation resolved. It is helpful to supply the commit in your reply if one was submitted to fix the issue.
|
||||
</list-item>
|
||||
</list>
|
||||
|
||||
<p>Lastly, thank you for contributing to <backrest/>!</p>
|
||||
</section>
|
||||
</doc>
|
||||
|
||||
@ -145,6 +145,17 @@
|
||||
|
||||
<release-doc-list>
|
||||
<release-improvement-list>
|
||||
<release-item>
|
||||
<github-pull-request id="1469"/>
|
||||
|
||||
<release-item-contributor-list>
|
||||
<release-item-contributor id="cynthia.shang"/>
|
||||
<release-item-reviewer id="david.steele"/>
|
||||
</release-item-contributor-list>
|
||||
|
||||
<p>Update contributing documentation and add pull request template.</p>
|
||||
</release-item>
|
||||
|
||||
<release-item>
|
||||
<release-item-contributor-list>
|
||||
<release-item-contributor id="cynthia.shang"/>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user