Add GH action to enforce @SInCE release vX.X.X, replace all offending

replace all tags add action add comments to action typo on return var dont local exit 1 with no ret fix since syntax use bashxargs should fail test exit zero when passing, 1 when failing clean last tags changelog
goatshriek · Sep 21, 2023 · 29a230d · 29a230d
1 parent 7a8c928
commit 29a230d
Show file tree

Hide file tree

Showing 13 changed files with 61 additions and 36 deletions.
diff --git a/.github/workflows/analysis.yml b/.github/workflows/analysis.yml
@@ -70,3 +70,27 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
           SONARQUBE_SCANNER_PARAMS: '{"sonar.host.url":"https://sonarcloud.io"}'
+  custom-anaysis:
+    name: Custom Analysis
+    runs-on: "ubuntu-latest"
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - name: "@since standardization"
+        run: |
+          # look for all instances of @since, then look for any that do not meet the required pattern. @since release x.x.x
+          if grep --include=\*.{c,h} -rnw . -e ".*@since .*" | grep -qv ".* @since release v[[:digit:]]\+\.[[:digit:]]\+\.[[:digit:]].*"; then
+            # at this point the check has failed, but we want to give some info to the user. i have found it difficult to get the status code
+            # and print out the offending lines without this duplication
+            # get all instances of @since, offending and not offending
+            grep --include=\*.{c,h} -rnw . -e "@since .*" | \
+            # find all instances that do not meet the required pattern
+            grep -v ".* @since release v[[:digit:]]\+\.[[:digit:]]\+\.[[:digit:]].*" | \
+            # print an error message, including line number with -n from grep. mention supported format. 
+            xargs -I{} echo "Static Analysis Failed:     \"{}\"      Supported format is \"@since release vX.X.X\""
+            exit 1
+          else
+            exit 0
+          fi
+
diff --git a/ChangeLog.md b/ChangeLog.md
@@ -8,7 +8,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 For a detailed look at the project's future, including planned features and bug
 fixes, check out the
 [roadmap](https://github.com/goatshriek/stumpless/blob/master/docs/roadmap.md).
-
+### Added 
+ - @since format check enforcement in CI pipeline.
 
 ## [2.2.0] - 2023-08-08
 ### Fixed

diff --git a/include/private/config/journald_supported.h b/include/private/config/journald_supported.h
@@ -36,7 +36,7 @@
  * This function is safe to call from threads that may be asynchronously
  * cancelled.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @param element The element to initialize.
  */
@@ -57,7 +57,7 @@ journald_init_journald_element( struct stumpless_element *element );
  * This function is safe to call from threads that may be asynchronously
  * cancelled.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @param param The param to initialize.
  */

diff --git a/include/private/error.h b/include/private/error.h
@@ -313,7 +313,7 @@ raise_windows_failure( const char *message, int code, const char *code_type );
  * cancelled, as the lock used to control access to the error stream may not
  * be released after a cancellation.
  *
- * @since v2.1.0.
+ * @since release v2.1.0.
  *
  * @param msg The message to be written to the error stream.
  *

diff --git a/include/private/target/journald.h b/include/private/target/journald.h
@@ -37,7 +37,7 @@
  * This function is safe to call from threads that may be asynchronously
  * cancelled.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @param flattened A buffer to write the flattened name to.
  *
@@ -65,7 +65,7 @@ get_journald_field_name( char *flattened, const char *raw, size_t size );
  * This function is not safe to call from threads that may be asynchronously
  * cancelled, as the memory allocation function may not be AC-Safe itself.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @param field_count The number of fields the buffer must have.
  */
@@ -87,7 +87,7 @@ init_fields( size_t field_count );
  * This function is not safe to call from threads that may be asynchronously
  * cancelled, as the memory allocation function may not be AC-Safe itself.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  */
 void
 init_fixed_fields( void );
@@ -107,7 +107,7 @@ init_fixed_fields( void );
  * This function is not safe to call from threads that may be asynchronously
  * cancelled, as the memory deallocation function may not be AC-Safe itself.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  */
 void
 journald_free_thread( void );
@@ -127,7 +127,7 @@ journald_free_thread( void );
  * Logging to journald targets is not async cancellation safe as it uses locks
  * that may not be released if a thread is cancelled.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @param entry The entry to load the facility from.
  */
@@ -149,7 +149,7 @@ load_facility( const struct stumpless_entry *entry );
  * Logging to journald targets is not async cancellation safe as it uses locks
  * that may not be released if a thread is cancelled.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @param entry The entry to load the identifier from.
  */
@@ -171,7 +171,7 @@ load_identifier( const struct stumpless_entry *entry );
  * Logging to journald targets is not async cancellation safe as it uses locks
  * that may not be released if a thread is cancelled.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @param entry The entry to load the message from.
  *
@@ -196,7 +196,7 @@ load_message( const struct stumpless_entry *entry );
  * Logging to journald targets is not async cancellation safe as it uses locks
  * that may not be released if a thread is cancelled.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @param entry The entry to load the msgid from.
  */
@@ -215,7 +215,7 @@ load_msgid( const struct stumpless_entry *entry );
  * **Async Cancel Safety: AC-Safe**
  * Logging to journald targets is async cancellation safe.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @return The size of the loaded pid, including the field prefix.
  */
@@ -237,7 +237,7 @@ load_pid( void );
  * Logging to journald targets is not async cancellation safe as it uses locks
  * that may not be released if a thread is cancelled.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @param entry The entry to load the priority from.
  */
@@ -260,7 +260,7 @@ load_priority( const struct stumpless_entry *entry );
  * Logging to journald targets is not async cancellation safe as it uses locks
  * that may not be released if a thread is cancelled.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @param entry The entry to load the fields from.
  *
@@ -284,7 +284,7 @@ load_sd_fields( const struct stumpless_entry *entry );
  * **Async Cancel Safety: AC-Safe**
  * Logging to journald targets is async cancellation safe.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @return The size of the loaded timestamp, including the field prefix.
  */
@@ -305,7 +305,7 @@ load_timestamp( void );
  * Logging to journald targets is not async cancellation safe as it relies on
  * sd_journal_sendv which is not documented as such.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @param target Where to send the entry.
  *
@@ -334,7 +334,7 @@ send_entry_to_journald_target( const struct stumpless_target *target,
  * This function is not async cancellation safe as it may leave the buffers in
  * an inconsistent state.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  */
 void
 set_field_bases( void );

diff --git a/include/stumpless/config/journald_supported.h b/include/stumpless/config/journald_supported.h
@@ -48,7 +48,7 @@ extern "C" {
  * This function is not safe to call from threads that may be asynchronously
  * cancelled, due to the use of a lock which could be left locked.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @param element The element to get the function of.
  *
@@ -76,7 +76,7 @@ stumpless_get_element_journald_namer( const struct stumpless_element *element );
  * This function is not safe to call from threads that may be asynchronously
  * cancelled, due to the use of a lock which could be left locked.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @param param The param to get the function of.
  *
@@ -104,7 +104,7 @@ stumpless_get_param_journald_namer( const struct stumpless_param *param );
  * This function is not safe to call from threads that may be asynchronously
  * cancelled, due to the use of a lock which could be left locked.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @param element The element to set the function of.
  *
@@ -134,7 +134,7 @@ stumpless_set_element_journald_namer( struct stumpless_element *element,
  * This function is not safe to call from threads that may be asynchronously
  * cancelled, due to the use of a lock which could be left locked.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @param param The param to set the function of.
  *

diff --git a/include/stumpless/element.h b/include/stumpless/element.h
@@ -61,7 +61,7 @@ struct stumpless_entry;
  * This function must be safe to call from threads that may be asynchronously
  * cancelled.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @param entry The entry that the param is part of.
  *

diff --git a/include/stumpless/entry.h b/include/stumpless/entry.h
@@ -953,7 +953,7 @@ stumpless_load_entry( struct stumpless_entry *entry,
  * This function has the same behavior as stumpless_load_entry_str, except it
  * does not create a new entry, instead loading an existing struct.
  *
- * @since version v2.2.0
+ * @since release v2.2.0
  *
  * @param facility The facility code of the event this entry describes. This
  * should be a \c STUMPLESS_FACILITY value.
@@ -1056,7 +1056,7 @@ stumpless_new_entry( enum stumpless_facility facility,
  * This function is not safe to call from threads that may be asynchronously
  * cancelled, due to the use of memory management functions.
  *
- * @since version v2.1.0
+ * @since release v2.1.0
  *
  * @param facility The facility code of the event this entry describes. This
  * should be a \c STUMPLESS_FACILITY value.

diff --git a/include/stumpless/error.h b/include/stumpless/error.h
@@ -203,7 +203,7 @@ stumpless_get_error( void );
  * This function is safe to call from threads that may be asynchronously
  * cancelled.
  *
- * @since Release v1.5.0
+ * @since release v1.5.0
  *
  * @param err The error to get the id from. This must not be NULL.
  *
@@ -228,7 +228,7 @@ stumpless_get_error_id( const struct stumpless_error *err );
  * This function is safe to call from threads that may be asynchronously
  * cancelled.
  *
- * @since Release v1.6.0
+ * @since release v1.6.0
  *
  * @param id The error id to get the error string from.
  *

diff --git a/include/stumpless/param.h b/include/stumpless/param.h
@@ -59,7 +59,7 @@ struct stumpless_entry;
  * This function must be safe to call from threads that may be asynchronously
  * cancelled.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @param entry The entry that the param is part of.
  *

diff --git a/include/stumpless/target.h b/include/stumpless/target.h
@@ -466,7 +466,7 @@ stumpless_close_target( struct stumpless_target *target );
  * This function is safe to call from threads that may be ansynchronously
  * cancelled.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @return The current stream where messages are logged to on setting the
  * the CONS option.
@@ -811,7 +811,7 @@ stumpless_open_target( struct stumpless_target *target );
  * This function is safe to call from threads that may be ansynchronously
  * cancelled.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @param stream The stream to write logs to. If this is NULL then the messages
  *	intended for the console stream will be ignored.

diff --git a/include/stumpless/target/function.h b/include/stumpless/target/function.h
@@ -73,7 +73,7 @@ typedef int ( *stumpless_log_func_t )( const struct stumpless_target *,
  * This function is not safe to call from threads that may be asynchronously
  * cancelled, as the memory deallocation function may not be AC-Safe itself.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @param target The function target to close.
  */
@@ -102,7 +102,7 @@ stumpless_close_function_target( const struct stumpless_target *target );
  * This function is not safe to call from threads that may be asynchronously
  * cancelled, as the memory allocation function may not be AC-Safe itself.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @param name The name of the logging target.
  *

diff --git a/include/stumpless/target/journald.h b/include/stumpless/target/journald.h
@@ -69,7 +69,7 @@ extern "C" {
  * This function is not safe to call from threads that may be asynchronously
  * cancelled, as the memory deallocation function may not be AC-Safe itself.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @param target The journald target to close.
  */
@@ -98,7 +98,7 @@ stumpless_close_journald_target( const struct stumpless_target *target );
  * This function is safe to call from threads that may be asynchronously
  * cancelled.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @param entry The entry that the param is part of.
  *
@@ -144,7 +144,7 @@ stumpless_flatten_element_name( const struct stumpless_entry *entry,
  * This function is safe to call from threads that may be asynchronously
  * cancelled.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @param entry The entry that the param is part of.
  *
@@ -185,7 +185,7 @@ stumpless_flatten_param_name( const struct stumpless_entry *entry,
  * This function is not safe to call from threads that may be asynchronously
  * cancelled, as the memory allocation function may not be AC-Safe itself.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @param name The name of the logging target.
  *