update project documentation (#425)

Add and update documentation for parts of the project structure
and governance.

The codecov upload action is also updated here, to attempt to fix some
repeated failures of the github actions using it.

.github/pull_request_template.md

@@ -3,4 +3,4 @@ things at a high level. If this request is in response to a particular issue,
 include a reference to it here.
 
 Make sure that your pull request follows the guidelines specified in the
-[Guidelines for Contributing](../docs/CONTRIBUTING.md). 
+[Guidelines for Contributing](https://github.com/goatshriek/stumpless/blob/latest/docs/CONTRIBUTING.md).

.github/workflows/linux.yml

@@ -40,7 +40,7 @@ jobs:
           sudo ./function-test-udp6
           sudo ./function-test-udp6_leak
       - name: Codecov Upload
-        uses: codecov/codecov-action@84508663e988701840491b86de86b666e8a86bed # v4.3.0
+        uses: codecov/codecov-action@e28ff129e5465c2c0dcc6f003fc735cb6ae0c673 # v4.5.0
         with:
           disable_file_fixes: true
           fail_ci_if_error: true
@@ -95,7 +95,7 @@ jobs:
           sudo ./function-test-udp6
           sudo ./function-test-udp6_leak
       - name: Codecov Upload
-        uses: codecov/codecov-action@84508663e988701840491b86de86b666e8a86bed # v4.3.0
+        uses: codecov/codecov-action@e28ff129e5465c2c0dcc6f003fc735cb6ae0c673 # v4.5.0
         with:
           disable_file_fixes: true
           fail_ci_if_error: true
@@ -290,7 +290,7 @@ jobs:
           make check
           if grep "DEPRECATED" Testing/Temporary/LastTest.log; then exit 1; fi
       - name: Codecov Upload
-        uses: codecov/codecov-action@84508663e988701840491b86de86b666e8a86bed # v4.3.0
+        uses: codecov/codecov-action@e28ff129e5465c2c0dcc6f003fc735cb6ae0c673 # v4.5.0
         with:
           disable_file_fixes: true
           fail_ci_if_error: true

.github/workflows/mac.yml

@@ -36,7 +36,7 @@ jobs:
           sudo ./function-test-udp6
           sudo ./function-test-udp6_leak
       - name: Codecov Upload
-        uses: codecov/codecov-action@84508663e988701840491b86de86b666e8a86bed # v4.3.0
+        uses: codecov/codecov-action@e28ff129e5465c2c0dcc6f003fc735cb6ae0c673 # v4.5.0
         with:
           disable_file_fixes: true
           fail_ci_if_error: true
@@ -163,7 +163,7 @@ jobs:
           make check
           if grep "DEPRECATED" Testing/Temporary/LastTest.log; then exit 1; fi
       - name: Codecov Upload
-        uses: codecov/codecov-action@84508663e988701840491b86de86b666e8a86bed # v4.3.0
+        uses: codecov/codecov-action@e28ff129e5465c2c0dcc6f003fc735cb6ae0c673 # v4.5.0
         with:
           disable_file_fixes: true
           fail_ci_if_error: true

README.md

@@ -29,9 +29,8 @@ Stumpless has lots of features that make logging in C fast and easy:
  * builds on Linux, Windows, Mac, FreeBSD, MinGW, MSYS2, Cygwin, DOS, and more!
  * thread safe
  * can be adjusted or removed during compilation for zero runtime cost
- * localized for multiple languages :albania: :brazil: :bulgaria: :cn:
-   :czech_republic: :de: :denmark: :es: :fr: :greece: :hungary: :india:
-   :israel: :it: :jp: :kenya: :poland: :slovakia: :sri_lanka: :sweden: :tr: :us: :ko:
+ * localized for multiple languages 🇦🇱 🇧🇷 🇧🇬 🇨🇳 🇨🇿 🇩🇪 🇩🇰 🇪🇸 🇫🇷 🇬🇷 🇭🇺 🇮🇳 🇮🇱 🇮🇹
+   🇯🇵 🇰🇪 🇰🇷 🇵🇱 🇸🇰 🇱🇰 🇸🇪 🇹🇷 🇺🇸
    ([add yours!](https://github.com/goatshriek/stumpless/blob/latest/docs/localization.md))
  * easy-access
    [documentation](https://goatshriek.github.io/stumpless/docs/c/latest/index.html),

docs/CONTRIBUTING.md

@@ -110,14 +110,16 @@ To create your own feature or update, you should fork the repository and create
 a new branch based on the `latest` branch. Don't forget to update the ChangeLog
 with your changes, and when you're ready open a pull request against `latest`.
 
-It is unusual, but you may find that it is more appropriate to base your branch
-on the `release` branch instead of `latest`. Some examples of these types of
-changes are:
- * updates to project documentation that is relevant to the current version of
-   the project as well as the next
- * patches that need to be applied to the current version of the library in
-   order to fix broken functionality (note that this will require updating the
-   library to the next patch level, for example from 1.3.2 to 1.3.3)
+It is unusual, but you may find that it is best to base your work on the
+`release` branch instead of `latest`. This is a lot more work than using
+`latest` though, since the changes still need to be merged into `latest` which
+may have diverged enough to cause conflicts. It will also probably require
+cutting a new patch-level release with the changes. So don't do this unless
+it's truly necessary, as in these cases:
+ * patches need to be applied to the last release in order to fix broken
+   functionality
+ * critical updates to documentation that could cause serious misuse or breakage
+   if not corrected
 
 Be sure to check out the [dependencies](dependencies.md) list to make sure that
 your development environment has all of the necessary tools. More specifically,

docs/localization.md

@@ -54,15 +54,15 @@ value of the string must be equal to the `en-us` value as a fallback. The
 `scripts/check_l10n.rb` script can check this, and is run during integration
 tests on all headers.
 
-The `scripts/add_l10n_scripts.rb` provides a quick way to do all of this for new
+The `scripts/add_l10n_string.rb` provides a quick way to do all of this for new
 strings. Run it with the name of the new string and the english translation,
 and it will insert placeholders into all locale headers. Here's an example
 invocation:
 
 ```sh
 # this will result in a string of L10N_TEST_STR being added to all locale
 # headers with the english translation of "this is a test string"
-ruby scripts/add_l10n_scripts.rb TEST_STR this is a test string
+ruby scripts/add_l10n_string.rb TEST_STR this is a test string
 ```
 
 

tools/README.md

@@ -0,0 +1,37 @@
+# Development Tools
+Stumpless uses both custom and external tools to make development easier,
+implement features, and maintain the code base. This directory has files that
+are specific to these tools such as configuration files and scripts.
+
+
+## [`check_headers`](./check_headers)
+A custom tool written to make sure that appropriate headers are included in
+sources according to project conventions.
+
+
+## [`cmake`](./cmake)
+CMake scripts used in the configuration and build of Stumpless.
+
+
+## [`doxygen`](./doxygen)
+Configuration files for generating project documentation with Doxygen.
+
+
+## [`pkg-config`](./pkg-config)
+Configuration for `pkg-config` support.
+
+
+## [`portage`](./portage)
+Packaging files for Gentoo's Portage system.
+
+
+## [`sonar`](./sonar)
+Configuration for Sonarcloud code scanning and analysis.
+
+
+## [`valgrind`](./valgrind)
+Configuration files for valgrind, including false positive annotations.
+
+
+## [`wrapture`](./wrapture)
+Templates for generating C++ language bindings with Wrapture.