mirror of
https://github.com/pgbackrest/pgbackrest.git
synced 2024-12-12 10:04:14 +02:00
Update contributing.xml with rendering changes from def7d513.
Also update help.xml path missed in f4e1babf.
This commit is contained in:
David Steele
parent
90c73183ea
commit
1212668d5e
@ -570,7 +570,7 @@ To add an option, two files need be to be modified:
|
||||
|
||||
- `src/build/config/config.yaml`
|
||||
|
||||
- `src/build/config/help.xml`
|
||||
- `src/build/help/help.xml`
|
||||
|
||||
These files are discussed in the following sections along with how to verify the `help` command output.
|
||||
|
||||
@ -601,16 +601,12 @@ Note that `section:` is not present thereby making this a command-line only opti
|
||||
|
||||
- `type` - the type of the option. Valid values for types are: `boolean`, `hash`, `integer`, `list`, `path`, `size`, `string`, and `time`
|
||||
|
||||
|
||||
- `command` - list each command for which the option is valid. If a command is not listed, then the option is not valid for the command and an error will be thrown if it is attempted to be used for that command. In this case the valid commands are `backup` and `restore`.
|
||||
|
||||
|
||||
- `backup` - details the requirements for the `--set` option for the `backup` command. It is dependent on the option `--stanza`, meaning it is only allowed to be specified for the `backup` command if the `--stanza` option has been specified. And `required: false` indicates that the `--set` option is never required, even with the dependency.
|
||||
|
||||
|
||||
- `restore` - details the requirements for the `--set` option for the `restore` command. Since `required:` is omitted, it is not required to be set by the user but it is required by the command and will default to `latest` if it has not been specified by the user.
|
||||
|
||||
|
||||
- `command-role` - defines the processes for which the option is valid. `main` indicates the option will be used by the main process and not be passed on to other local/remote processes.
|
||||
|
||||
#### EXAMPLE 2 hypothetical configuration file option
|
||||
@ -633,28 +629,20 @@ repo-test-type:
|
||||
|
||||
- `repo-test-type` - the name of the option
|
||||
|
||||
|
||||
- `section` - the section of the configuration file where this option is valid (omitted for command line only options, see [Example 1](#example-1-hypothetical-command-line-only-option) above)
|
||||
|
||||
|
||||
- `type` - the type of the option. Valid values for types are: `boolean`, `hash`, `integer`, `list`, `path`, `size`, `string`, and `time`
|
||||
|
||||
|
||||
- `group` - indicates that this option is part of the `repo` group of indexed options and therefore will follow the indexing rules e.g. `repo1-test-type`.
|
||||
|
||||
|
||||
- `default` - sets a default for the option if the option is not provided when the command is run. The default can be global (as it is here) or it can be specified for a specific command in the command section (as in [Example 1](#example-1-hypothetical-command-line-only-option) above).
|
||||
|
||||
|
||||
- `allow-list` - lists the allowable values for the option for all commands for which the option is valid.
|
||||
|
||||
|
||||
- `command` - list each command for which the option is valid. If a command is not listed, then the option is not valid for the command and an error will be thrown if it is attempted to be used for that command. In this case the valid commands are `backup` and `restore`.
|
||||
|
||||
|
||||
- `command-role` - defines the processes for which the option is valid. `main` indicates the option will be used by the main process and not be passed on to other local/remote processes.
|
||||
|
||||
|
||||
At compile time, the `config.auto.h` file will be generated to contain the constants used for options in the code. For the C enums, any dashes in the option name will be removed, camel-cased and prefixed with `cfgOpt`, e.g. `repo-path` becomes `cfgOptRepoPath`.
|
||||
|
||||
### help.xml
|
||||
@ -710,30 +698,22 @@ 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!
|
||||
|
||||
@ -60,15 +60,15 @@
|
||||
<section id="introduction">
|
||||
<title>Introduction</title>
|
||||
|
||||
<p>This documentation is intended to assist contributors to <backrest/> by outlining some basic steps and guidelines for contributing to the project.
|
||||
<p>This documentation is intended to assist contributors to <backrest/> by outlining some basic steps and guidelines for contributing to the project.</p>
|
||||
|
||||
Code fixes or new features can be submitted via pull requests. Ideas for new features and improvements to existing functionality or documentation can be <link url="{[github-url-issues]}">submitted as issues</link>. You may want to check the <link url="{[github-url-projects]}">Project Boards</link> to see if your suggestion has already been submitted.
|
||||
<p>Code fixes or new features can be submitted via pull requests. Ideas for new features and improvements to existing functionality or documentation can be <link url="{[github-url-issues]}">submitted as issues</link>. You may want to check the <link url="{[github-url-projects]}">Project Boards</link> to see if your suggestion has already been submitted.</p>
|
||||
|
||||
Bug reports should be <link url="{[github-url-issues]}">submitted as issues</link>. Please provide as much information as possible to aid in determining the cause of the problem.
|
||||
<p>Bug reports should be <link url="{[github-url-issues]}">submitted as issues</link>. Please provide as much information as possible to aid in determining the cause of the problem.</p>
|
||||
|
||||
You will always receive credit in the <link page="{[backrest-page-release]}">release notes</link> for your contributions.
|
||||
<p>You will always receive credit in the <link page="{[backrest-page-release]}">release notes</link> for your contributions.</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>
|
||||
<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>
|
||||
|
||||
<!-- ======================================================================================================================= -->
|
||||
@ -587,9 +587,9 @@ pgbackrest/test/test.pl --vm-out --module=command --test=check --vm=u20
|
||||
|
||||
<admonition type="note">Not all systems perform at the same speed, so if a test is timing out, try rerunning with another vm.</admonition>
|
||||
|
||||
<p>Because a test run has not been specified, a coverage report will be generated and written to the local file system under the <backrest/> directory <file>test/result/coverage/lcov/index.html</file> and a file with only the highlighted code that has not been covered will be written to <file>test/result/coverage/coverage.html</file>.
|
||||
<p>Because a test run has not been specified, a coverage report will be generated and written to the local file system under the <backrest/> directory <file>test/result/coverage/lcov/index.html</file> and a file with only the highlighted code that has not been covered will be written to <file>test/result/coverage/coverage.html</file>.</p>
|
||||
|
||||
If 100 percent code coverage has not been achieved, an error message will be displayed, for example: <code>ERROR: [125]: c module command/check/check is not fully covered</code></p>
|
||||
<p>If 100 percent code coverage has not been achieved, an error message will be displayed, for example: <code>ERROR: [125]: c module command/check/check is not fully covered</code></p>
|
||||
|
||||
<p><b>Debugging with files</b></p>
|
||||
|
||||
@ -665,16 +665,11 @@ run 8/1 ------------- L2285 no current backups
|
||||
|
||||
<list>
|
||||
<list-item><id>set</id> - the name of the option</list-item>
|
||||
<list-item><id>type</id> - the type of the option. Valid values for types are: <id>boolean</id>, <id>hash</id>, <id>integer</id>, <id>list</id>, <id>path</id>, <id>size</id>, <id>string</id>, and <id>time</id>
|
||||
</list-item>
|
||||
<list-item><id>command</id> - list each command for which the option is valid. If a command is not listed, then the option is not valid for the command and an error will be thrown if it is attempted to be used for that command. In this case the valid commands are <cmd>backup</cmd> and <cmd>restore</cmd>.
|
||||
</list-item>
|
||||
<list-item><id>backup</id> - details the requirements for the <code>--set</code> option for the <cmd>backup</cmd> command. It is dependent on the option <code>--stanza</code>, meaning it is only allowed to be specified for the <cmd>backup</cmd> command if the <code>--stanza</code> option has been specified. And <code>required: false</code> indicates that the <code>--set</code> option is never required, even with the dependency.
|
||||
</list-item>
|
||||
<list-item><id>restore</id> - details the requirements for the <code>--set</code> option for the <cmd>restore</cmd> command. Since <code>required:</code> is omitted, it is not required to be set by the user but it is required by the command and will default to <code>latest</code> if it has not been specified by the user.
|
||||
</list-item>
|
||||
<list-item><id>command-role</id> - defines the processes for which the option is valid. <code>main</code> indicates the option will be used by the main process and not be passed on to other local/remote processes.
|
||||
</list-item>
|
||||
<list-item><id>type</id> - the type of the option. Valid values for types are: <id>boolean</id>, <id>hash</id>, <id>integer</id>, <id>list</id>, <id>path</id>, <id>size</id>, <id>string</id>, and <id>time</id></list-item>
|
||||
<list-item><id>command</id> - list each command for which the option is valid. If a command is not listed, then the option is not valid for the command and an error will be thrown if it is attempted to be used for that command. In this case the valid commands are <cmd>backup</cmd> and <cmd>restore</cmd>.</list-item>
|
||||
<list-item><id>backup</id> - details the requirements for the <code>--set</code> option for the <cmd>backup</cmd> command. It is dependent on the option <code>--stanza</code>, meaning it is only allowed to be specified for the <cmd>backup</cmd> command if the <code>--stanza</code> option has been specified. And <code>required: false</code> indicates that the <code>--set</code> option is never required, even with the dependency.</list-item>
|
||||
<list-item><id>restore</id> - details the requirements for the <code>--set</code> option for the <cmd>restore</cmd> command. Since <code>required:</code> is omitted, it is not required to be set by the user but it is required by the command and will default to <code>latest</code> if it has not been specified by the user.</list-item>
|
||||
<list-item><id>command-role</id> - defines the processes for which the option is valid. <code>main</code> indicates the option will be used by the main process and not be passed on to other local/remote processes.</list-item>
|
||||
</list>
|
||||
|
||||
<section id="option-ex2">
|
||||
@ -699,22 +694,14 @@ run 8/1 ------------- L2285 no current backups
|
||||
</section>
|
||||
|
||||
<list>
|
||||
<list-item><id>repo-test-type</id> - the name of the option
|
||||
</list-item>
|
||||
<list-item><id>section</id> - the section of the configuration file where this option is valid (omitted for command line only options, see <link section="/option/config-file/option-ex1">Example 1</link> above)
|
||||
</list-item>
|
||||
<list-item><id>type</id> - the type of the option. Valid values for types are: <id>boolean</id>, <id>hash</id>, <id>integer</id>, <id>list</id>, <id>path</id>, <id>size</id>, <id>string</id>, and <id>time</id>
|
||||
</list-item>
|
||||
<list-item><id>group</id> - indicates that this option is part of the <code>repo</code> group of indexed options and therefore will follow the indexing rules e.g. <code>repo1-test-type</code>.
|
||||
</list-item>
|
||||
<list-item><id>default</id> - sets a default for the option if the option is not provided when the command is run. The default can be global (as it is here) or it can be specified for a specific command in the command section (as in <link section="/option/config-file/option-ex1">Example 1</link> above).
|
||||
</list-item>
|
||||
<list-item><id>allow-list</id> - lists the allowable values for the option for all commands for which the option is valid.
|
||||
</list-item>
|
||||
<list-item><id>command</id> - list each command for which the option is valid. If a command is not listed, then the option is not valid for the command and an error will be thrown if it is attempted to be used for that command. In this case the valid commands are <cmd>backup</cmd> and <cmd>restore</cmd>.
|
||||
</list-item>
|
||||
<list-item><id>command-role</id> - defines the processes for which the option is valid. <code>main</code> indicates the option will be used by the main process and not be passed on to other local/remote processes.
|
||||
</list-item>
|
||||
<list-item><id>repo-test-type</id> - the name of the option</list-item>
|
||||
<list-item><id>section</id> - the section of the configuration file where this option is valid (omitted for command line only options, see <link section="/option/config-file/option-ex1">Example 1</link> above)</list-item>
|
||||
<list-item><id>type</id> - the type of the option. Valid values for types are: <id>boolean</id>, <id>hash</id>, <id>integer</id>, <id>list</id>, <id>path</id>, <id>size</id>, <id>string</id>, and <id>time</id></list-item>
|
||||
<list-item><id>group</id> - indicates that this option is part of the <code>repo</code> group of indexed options and therefore will follow the indexing rules e.g. <code>repo1-test-type</code>.</list-item>
|
||||
<list-item><id>default</id> - sets a default for the option if the option is not provided when the command is run. The default can be global (as it is here) or it can be specified for a specific command in the command section (as in <link section="/option/config-file/option-ex1">Example 1</link> above).</list-item>
|
||||
<list-item><id>allow-list</id> - lists the allowable values for the option for all commands for which the option is valid.</list-item>
|
||||
<list-item><id>command</id> - list each command for which the option is valid. If a command is not listed, then the option is not valid for the command and an error will be thrown if it is attempted to be used for that command. In this case the valid commands are <cmd>backup</cmd> and <cmd>restore</cmd>.</list-item>
|
||||
<list-item><id>command-role</id> - defines the processes for which the option is valid. <code>main</code> indicates the option will be used by the main process and not be passed on to other local/remote processes.</list-item>
|
||||
</list>
|
||||
|
||||
<p>At compile time, the <file>config.auto.h</file> file will be generated to contain the constants used for options in the code. For the C enums, any dashes in the option name will be removed, camel-cased and prefixed with <code>cfgOpt</code>, e.g. <code>repo-path</code> becomes <code>cfgOptRepoPath</code>.</p>
|
||||
@ -790,31 +777,23 @@ pgbackrest/doc/doc.pl --out=html --include=user-guide --require=/quickstart --va
|
||||
<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-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-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-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>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user