From 430efff98a5b8dcf7c048f383abc12d9c0e5bbf0 Mon Sep 17 00:00:00 2001 From: David Steele Date: Wed, 13 Oct 2021 12:01:53 -0400 Subject: [PATCH] Update documentation/links to main branch. --- .github/pull_request_template.md | 2 +- CONTRIBUTING.md | 30 +++++++++++++++--------------- README.md | 4 ++-- doc/RELEASE.md | 10 +++++----- doc/xml/contributing.xml | 18 +++++++++--------- doc/xml/index.xml | 6 +++--- 6 files changed, 35 insertions(+), 35 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 7dc61f555..ba375925d 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1 +1 @@ -Please read [Submitting a Pull Request](https://github.com/pgbackrest/pgbackrest/blob/master/CONTRIBUTING.md#submitting-a-pull-request) before submitting. +Please read [Submitting a Pull Request](https://github.com/pgbackrest/pgbackrest/blob/main/CONTRIBUTING.md#submitting-a-pull-request) before submitting. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c4427a0e6..27efadb34 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -22,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](#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/main/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 @@ -51,7 +51,7 @@ pgbackrest-dev => Clone pgBackRest repository git clone https://github.com/pgbackrest/pgbackrest.git ``` -If using a RHEL-based system, the CPAN XML parser is required to run `test.pl` and `doc.pl`. Instructions for installing Docker and the XML parser can be found in the `README.md` file of the pgBackRest [doc](https://github.com/pgbackrest/pgbackrest/blob/master/doc) directory in the section "The following is a sample RHEL/CentOS 7 configuration that can be used for building the documentation". NOTE that the "Install latex (for building PDF)" section is not required since testing of the docs need only be run for HTML output. +If using a RHEL-based system, the CPAN XML parser is required to run `test.pl` and `doc.pl`. Instructions for installing Docker and the XML parser can be found in the `README.md` file of the pgBackRest [doc](https://github.com/pgbackrest/pgbackrest/blob/main/doc) directory in the section "The following is a sample RHEL/CentOS 7 configuration that can be used for building the documentation". NOTE that the "Install latex (for building PDF)" section is not required since testing of the docs need only be run for HTML output. ## Coding @@ -59,17 +59,17 @@ The following sections provide information on some important concepts needed for ### Memory Contexts -Memory is allocated inside contexts and can be long lasting (for objects) or temporary (for functions). In general, use `OBJ_NEW_BEGIN(MyObj)` for objects and `MEM_CONTEXT_TEMP_BEGIN()` for functions. See [memContext.h](https://github.com/pgbackrest/pgbackrest/blob/master/src/common/memContext.h) for more details and the [Coding Example](#coding-example) below. +Memory is allocated inside contexts and can be long lasting (for objects) or temporary (for functions). In general, use `OBJ_NEW_BEGIN(MyObj)` for objects and `MEM_CONTEXT_TEMP_BEGIN()` for functions. See [memContext.h](https://github.com/pgbackrest/pgbackrest/blob/main/src/common/memContext.h) for more details and the [Coding Example](#coding-example) below. ### Logging -Logging is used for debugging with the built-in macros `FUNCTION_LOG_*()` and `FUNCTION_TEST_*()` which are used to trace parameters passed to/returned from functions. `FUNCTION_LOG_*()` macros are used for production logging whereas `FUNCTION_TEST_*()` macros will be compiled out of production code. For functions where no parameter is valuable enough to justify the cost of debugging in production, use `FUNCTION_TEST_BEGIN()/FUNCTION_TEST_END()`, else use `FUNCTION_LOG_BEGIN(someLogLevel)/FUNCTION_LOG_END()`. See [debug.h](https://github.com/pgbackrest/pgbackrest/blob/master/src/common/debug.h) for more details and the [Coding Example](#coding-example) below. +Logging is used for debugging with the built-in macros `FUNCTION_LOG_*()` and `FUNCTION_TEST_*()` which are used to trace parameters passed to/returned from functions. `FUNCTION_LOG_*()` macros are used for production logging whereas `FUNCTION_TEST_*()` macros will be compiled out of production code. For functions where no parameter is valuable enough to justify the cost of debugging in production, use `FUNCTION_TEST_BEGIN()/FUNCTION_TEST_END()`, else use `FUNCTION_LOG_BEGIN(someLogLevel)/FUNCTION_LOG_END()`. See [debug.h](https://github.com/pgbackrest/pgbackrest/blob/main/src/common/debug.h) for more details and the [Coding Example](#coding-example) below. -Logging is also used for providing information to the user via the `LOG_*()` macros, such as `LOG_INFO("some informational message")` and `LOG_WARN_FMT("no prior backup exists, %s backup has been changed to full", strZ(cfgOptionDisplay(cfgOptType)))` and also via `THROW_*()` macros for throwing an error. See [log.h](https://github.com/pgbackrest/pgbackrest/blob/master/src/common/log.h) and [error.h](https://github.com/pgbackrest/pgbackrest/blob/master/src/common/error.h) for more details and the [Coding Example](#coding-example) below. +Logging is also used for providing information to the user via the `LOG_*()` macros, such as `LOG_INFO("some informational message")` and `LOG_WARN_FMT("no prior backup exists, %s backup has been changed to full", strZ(cfgOptionDisplay(cfgOptType)))` and also via `THROW_*()` macros for throwing an error. See [log.h](https://github.com/pgbackrest/pgbackrest/blob/main/src/common/log.h) and [error.h](https://github.com/pgbackrest/pgbackrest/blob/main/src/common/error.h) for more details and the [Coding Example](#coding-example) below. ### Coding Example -The example below is not structured like an actual implementation and is intended only to provide an understanding of some of the more common coding practices. The comments in the example are only here to explain the example and are not representative of the coding standards. Refer to the Coding Standards document ([CODING.md](https://github.com/pgbackrest/pgbackrest/blob/master/CODING.md)) and sections above for an introduction to the concepts provided here. For an actual implementation, see [db.h](https://github.com/pgbackrest/pgbackrest/blob/master/src/db/db.h) and [db.c](https://github.com/pgbackrest/pgbackrest/blob/master/src/db/db.c). +The example below is not structured like an actual implementation and is intended only to provide an understanding of some of the more common coding practices. The comments in the example are only here to explain the example and are not representative of the coding standards. Refer to the Coding Standards document ([CODING.md](https://github.com/pgbackrest/pgbackrest/blob/main/CODING.md)) and sections above for an introduction to the concepts provided here. For an actual implementation, see [db.h](https://github.com/pgbackrest/pgbackrest/blob/main/src/db/db.h) and [db.c](https://github.com/pgbackrest/pgbackrest/blob/main/src/db/db.c). #### Example: hypothetical basic object construction ```c @@ -201,7 +201,7 @@ While some files are automatically generated during `make`, others are generated ``` pgbackrest/test/test.pl --gen-only ``` -Prior to any submission, the html version of the documentation should also be run and the output checked by viewing the generated html on the local file system under `pgbackrest/doc/output/html`. More details can be found in the pgBackRest [doc/README.md](https://github.com/pgbackrest/pgbackrest/blob/master/doc/README.md) file. +Prior to any submission, the html version of the documentation should also be run and the output checked by viewing the generated html on the local file system under `pgbackrest/doc/output/html`. More details can be found in the pgBackRest [doc/README.md](https://github.com/pgbackrest/pgbackrest/blob/main/doc/README.md) file. ``` pgbackrest/doc/doc.pl --out=html ``` @@ -221,7 +221,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`. 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`. +- `--vm` - identifies the pre-built container when using Docker, otherwise the setting should be `none`. See [test.yml](https://github.com/pgbackrest/pgbackrest/blob/main/.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: ``` @@ -413,7 +413,7 @@ if (testBegin("expireBackup()")) #### Setting up the command to be run -The [harnessConfig.h](https://github.com/pgbackrest/pgbackrest/blob/master/test/src/common/harnessConfig.h) describes a list of functions that should be used when configuration options are required for a command being tested. Options are set in a `StringList` which must be defined and passed to the `HRN_CFG_LOAD()` macro with the command. For example, the following will set up a test to run `pgbackrest --repo-path=test/test-0/repo info` command on multiple repositories, one of which is encrypted: +The [harnessConfig.h](https://github.com/pgbackrest/pgbackrest/blob/main/test/src/common/harnessConfig.h) describes a list of functions that should be used when configuration options are required for a command being tested. Options are set in a `StringList` which must be defined and passed to the `HRN_CFG_LOAD()` macro with the command. For example, the following will set up a test to run `pgbackrest --repo-path=test/test-0/repo info` command on multiple repositories, one of which is encrypted: ``` StringList *argList = strLstNew(); // Create an empty string list hrnCfgArgRawZ(argList, cfgOptRepoPath, TEST_PATH "/repo"); // Add the --repo-path option @@ -425,7 +425,7 @@ HRN_CFG_LOAD(cfgCmdInfo, argList); // Load the #### Storing a file -Sometimes it is desirable to store or manipulate files before or during a test and then confirm the contents. The [harnessStorage.h](https://github.com/pgbackrest/pgbackrest/blob/master/test/src/common/harnessStorage.h) file contains macros (e.g. `HRN_STORAGE_PUT` and `TEST_STORAGE_GET`) for doing this. In addition, `HRN_INFO_PUT` is convenient for writing out info files (archive.info, backup.info, backup.manifest) since it will automatically add header and checksum information. +Sometimes it is desirable to store or manipulate files before or during a test and then confirm the contents. The [harnessStorage.h](https://github.com/pgbackrest/pgbackrest/blob/main/test/src/common/harnessStorage.h) file contains macros (e.g. `HRN_STORAGE_PUT` and `TEST_STORAGE_GET`) for doing this. In addition, `HRN_INFO_PUT` is convenient for writing out info files (archive.info, backup.info, backup.manifest) since it will automatically add header and checksum information. ``` HRN_STORAGE_PUT_EMPTY( storageRepoWrite(), STORAGE_REPO_ARCHIVE "/10-1/000000010000000100000001-abcdabcdabcdabcdabcdabcdabcdabcdabcdabcd.gz"); @@ -433,7 +433,7 @@ HRN_STORAGE_PUT_EMPTY( #### Testing results -Tests are run and results confirmed via macros that are described in [harnessTest.h](https://github.com/pgbackrest/pgbackrest/blob/master/test/src/common/harnessTest.h). With the exception of TEST_ERROR, the third parameter is a short description of the test. Some of the more common macros are: +Tests are run and results confirmed via macros that are described in [harnessTest.h](https://github.com/pgbackrest/pgbackrest/blob/main/test/src/common/harnessTest.h). With the exception of TEST_ERROR, the third parameter is a short description of the test. Some of the more common macros are: - `TEST_RESULT_STR` - Test the actual value of the string returned by the function. @@ -459,7 +459,7 @@ In the above, `Pxx` indicates the process (P) and the process number (xx), e.g. #### Testing using child process -Sometimes it is useful to use a child process for testing. Below is a simple example. See [harnessFork.h](https://github.com/pgbackrest/pgbackrest/blob/master/test/src/common/harnessFork.h) for more details. +Sometimes it is useful to use a child process for testing. Below is a simple example. See [harnessFork.h](https://github.com/pgbackrest/pgbackrest/blob/main/test/src/common/harnessFork.h) for more details. ``` HRN_FORK_BEGIN() { @@ -505,7 +505,7 @@ HRN_FORK_END(); #### Testing using a shim -A PostgreSQL libpq shim is provided to simulate interactions with PostgreSQL. Below is a simple example. See [harnessPq.h](https://github.com/pgbackrest/pgbackrest/blob/master/test/src/common/harnessPq.h) for more details. +A PostgreSQL libpq shim is provided to simulate interactions with PostgreSQL. Below is a simple example. See [harnessPq.h](https://github.com/pgbackrest/pgbackrest/blob/main/test/src/common/harnessPq.h) for more details. ``` // Set up two standbys but no primary harnessPqScriptSet((HarnessPq []) @@ -578,7 +578,7 @@ These files are discussed in the following sections along with how to verify the There are detailed comment blocks above each section that explain the rules for defining commands and options. Regarding options, there are two types: 1) command line only, and 2) configuration file. With the exception of secrets, all configuration file options can be passed on the command line. To configure an option for the configuration file, the `section:` key must be present. -The `option:` section is broken into sub-sections by a simple comment divider (e.g. `# Repository options`) under which the options are organized alphabetically by option name. To better explain this section, two hypothetical examples will be discussed. For more details, see [config.yaml](https://github.com/pgbackrest/pgbackrest/blob/master/src/build/config/config.yaml). +The `option:` section is broken into sub-sections by a simple comment divider (e.g. `# Repository options`) under which the options are organized alphabetically by option name. To better explain this section, two hypothetical examples will be discussed. For more details, see [config.yaml](https://github.com/pgbackrest/pgbackrest/blob/main/src/build/config/config.yaml). #### EXAMPLE 1 hypothetical command line only option ``` @@ -696,7 +696,7 @@ The resulting Docker containers can be listed with `docker ps` and the container Before submitting a Pull Request: -- Does it meet the [coding standards](https://github.com/pgbackrest/pgbackrest/blob/master/CODING.md)? +- Does it meet the [coding standards](https://github.com/pgbackrest/pgbackrest/blob/main/CODING.md)? - Have [Unit Tests](#writing-a-unit-test) been written and [run](#running-a-unit-test) with 100% coverage? diff --git a/README.md b/README.md index 0cd68610b..5633ef90c 100644 --- a/README.md +++ b/README.md @@ -102,11 +102,11 @@ pgBackRest strives to be easy to configure and operate: ## Contributions -Contributions to pgBackRest are always welcome! Please see our [Contributing Guidelines](https://github.com/pgbackrest/pgbackrest/blob/master/CONTRIBUTING.md) for details on how to contribute features, improvements or issues. +Contributions to pgBackRest are always welcome! Please see our [Contributing Guidelines](https://github.com/pgbackrest/pgbackrest/blob/main/CONTRIBUTING.md) for details on how to contribute features, improvements or issues. ## Support -pgBackRest is completely free and open source under the [MIT](https://github.com/pgbackrest/pgbackrest/blob/master/LICENSE) license. You may use it for personal or commercial purposes without any restrictions whatsoever. Bug reports are taken very seriously and will be addressed as quickly as possible. +pgBackRest is completely free and open source under the [MIT](https://github.com/pgbackrest/pgbackrest/blob/main/LICENSE) license. You may use it for personal or commercial purposes without any restrictions whatsoever. Bug reports are taken very seriously and will be addressed as quickly as possible. Creating a robust disaster recovery policy with proper replication and backup strategies can be a very complex and daunting task. You may find that you need help during the architecture phase and ongoing support to ensure that your enterprise continues running smoothly. diff --git a/doc/RELEASE.md b/doc/RELEASE.md index abdd85e4b..cc9482e3a 100644 --- a/doc/RELEASE.md +++ b/doc/RELEASE.md @@ -116,9 +116,9 @@ Documentation Features: Commit to integration with the above message and push to CI. -## Push to master +## Push to main -Push release commit to master once CI testing is complete. +Push release commit to main once CI testing is complete. ## Create release on github @@ -140,13 +140,13 @@ v2.14: Bug Fix and Improvements - Add user guide for RHEL/CentOS 7. ``` -The first line will be the release title and the rest will be the body. The tag field should be updated with the current version so a tag is created from master. **Be sure to select the release commit explicitly rather than auto-tagging the last commit in master!** +The first line will be the release title and the rest will be the body. The tag field should be updated with the current version so a tag is created from main. **Be sure to select the release commit explicitly rather than auto-tagging the last commit in main!** -## Push web documentation to master and deploy +## Push web documentation to main and deploy ``` cd ${PGBR_REPO?}/doc/site git commit -m "v2.14 documentation." -git push origin master +git push origin main ``` Deploy the documentation on `pgbackrest.org`. diff --git a/doc/xml/contributing.xml b/doc/xml/contributing.xml index 96e13c5c4..119c69b20 100644 --- a/doc/xml/contributing.xml +++ b/doc/xml/contributing.xml @@ -15,9 +15,9 @@ {[host-user]} pgbackrest/doc:contrib - {[github-url-master]}/test/src - {[github-url-master]}/test/src/common - {[github-url-master]}/src + {[github-url-main]}/test/src + {[github-url-main]}/test/src/common + {[github-url-main]}/src {[github-url-src]}/common use Cwd qw(cwd); cwd() @@ -68,7 +68,7 @@

You will always receive credit in the release notes for your contributions.

-

Coding standards are defined in CODING.md and some important coding details and an example are provided in the 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 section below for details.

+

Coding standards are defined in CODING.md and some important coding details and an example are provided in the 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 section below for details.

@@ -142,7 +142,7 @@ -

If using a RHEL-based system, the CPAN XML parser is required to run test.pl and doc.pl. Instructions for installing Docker and the XML parser can be found in the README.md file of the doc directory in the section The following is a sample RHEL/CentOS 7 configuration that can be used for building the documentation. NOTE that the Install latex (for building PDF) section is not required since testing of the docs need only be run for HTML output.

+

If using a RHEL-based system, the CPAN XML parser is required to run test.pl and doc.pl. Instructions for installing Docker and the XML parser can be found in the README.md file of the doc directory in the section The following is a sample RHEL/CentOS 7 configuration that can be used for building the documentation. NOTE that the Install latex (for building PDF) section is not required since testing of the docs need only be run for HTML output.

@@ -167,7 +167,7 @@
Coding Example -

The example below is not structured like an actual implementation and is intended only to provide an understanding of some of the more common coding practices. The comments in the example are only here to explain the example and are not representative of the coding standards. Refer to the Coding Standards document (CODING.md) and sections above for an introduction to the concepts provided here. For an actual implementation, see db.h and db.c.

+

The example below is not structured like an actual implementation and is intended only to provide an understanding of some of the more common coding practices. The comments in the example are only here to explain the example and are not representative of the coding standards. Refer to the Coding Standards document (CODING.md) and sections above for an introduction to the concepts provided here. For an actual implementation, see db.h and db.c.

Example: hypothetical basic object construction @@ -308,7 +308,7 @@ myObjToLog(const MyObj *this) pgbackrest/test/test.pl --gen-only -

Prior to any submission, the html version of the documentation should also be run and the output checked by viewing the generated html on the local file system under pgbackrest/doc/output/html. More details can be found in the doc/README.md file.

+

Prior to any submission, the html version of the documentation should also be run and the output checked by viewing the generated html on the local file system under pgbackrest/doc/output/html. More details can be found in the doc/README.md file.

pgbackrest/doc/doc.pl --out=html @@ -326,7 +326,7 @@ myObjToLog(const MyObj *this) --test - the actual test set to be run --run - a number identifying the run within a test if testing a single run rather than the entire test --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. See test.yml for a list of valid vm codes noted by param: test. + --vm - identifies the pre-built container when using Docker, otherwise the setting should be none. See 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:

@@ -777,7 +777,7 @@ pgbackrest/doc/doc.pl --out=html --include=user-guide --require=/quickstart --va

Before submitting a Pull Request:

- Does it meet the coding standards? + Does it meet the coding standards? Have Unit Tests been written and run with 100% coverage? If your submission includes changes to the help or online documentation, have the help and 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. diff --git a/doc/xml/index.xml b/doc/xml/index.xml index 33ec9aaff..567f6bca1 100644 --- a/doc/xml/index.xml +++ b/doc/xml/index.xml @@ -7,12 +7,12 @@ https://github.com {[github-url-root]}/pgbackrest/pgbackrest - {[github-url-base]}/blob/master + {[github-url-base]}/blob/main {[github-url-base]}/issues {[github-url-base]}/archive/release - {[github-url-master]}/LICENSE + {[github-url-main]}/LICENSE {[github-url-base]}/projects - {[github-url-master]}/CONTRIBUTING.md + {[github-url-main]}/CONTRIBUTING.md http://www.pgbackrest.org user-guide-index