diff --git a/.github/workflows/analysis.yml b/.github/workflows/analysis.yml index 83a136b96..57c5862ac 100644 --- 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 index 76cb6ebf8..4b2e6786e 100644 --- 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 index 74103cc25..f21da3683 100644 --- 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 index 4a3b7a271..3defdbb9d 100644 --- 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 index d098e4676..4bd38cded 100644 --- 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 index 61b2b2f01..3bf1a6caa 100644 --- 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 index 3e9b913d3..d3f9674fd 100644 --- 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 index 5411ae9a2..a92587cd9 100644 --- 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 index 2286a7e36..124223a59 100644 --- 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 index 20f0c008d..aa8a96e26 100644 --- 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 index 9ec701adf..cd4801395 100644 --- 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 index 0193839cd..9350f994f 100644 --- 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 index 5387a747f..d25504c84 100644 --- 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. *