Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

add common mistakes documentation #394

Merged
merged 6 commits into from
Dec 10, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 26 additions & 5 deletions docs/development.md
Original file line number Diff line number Diff line change
Expand Up @@ -204,6 +204,11 @@ add it to the `.def` file so that the DLL will include it. Failing to do so
will result in tests failing on Windows builds with a note that your new
function is not defined. The Windows CI builds typically catch this issue.

Finally, be sure that you've added your new function to the appropriate header
check tool YAML file. To find out what that is, see the next section below!


## Header Checks
Stumpless uses a custom tool to make sure that all required headers are included
in a source file without any extras. The tool is called `check_headers` and is
stored in the `tools/check_headers` folder. You can run this manually if you
Expand Down Expand Up @@ -349,8 +354,24 @@ make bench
```


## Other development notes
For a detailed discussion of the performance testing framework used to gauge
the speed and efficiency of various calls, check out the
[benchmark](benchmark.md) documentation for the basic strategy and a full
walkthrough of an example.
## Common Mistakes
The project team sees a few types of issues happen more commonly than others.
Here are a few tips that will help you get your contribution accepted faster by
avoiding some back-and-forth change requests.
* **Forgetting to run header checks**
By far, missing headers are the most common cause of CI failure in new
contributions. Taking the extra time to run the
[header checks](#header-checks) locally before you open a pull request can
make the difference between a pull request being accepted and changes being
requested.
* **Force Pushing**
It's common (and expected) for changes to be requested on contributions. When
this happens, the best thing you can do is address these in a single commit
and push the new commit to your pull request branch. This makes it easy to
follow what changes were made, and speeds up the review process. While it
might seem cleaner to amend or squash your changes into a single new commit
and force-push it, please don't do this! It means that the entire
contribution must be reviewed again, and can make it harder to track comments
on individual lines of the commit. Most contributions are squashed into a
single commit when they are accepted, so never fear: the project team will
make sure that the end result of your hard work will be clean and neat!
4 changes: 2 additions & 2 deletions include/stumpless/facility.h
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
/* SPDX-License-Identifier: Apache-2.0 */

/*
* Copyright 2018-2020 Joel E. Anderson
* Copyright 2018-2023 Joel E. Anderson
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
Expand Down Expand Up @@ -410,7 +410,7 @@ stumpless_get_facility_enum( const char *facility_string );
* This function is safe to call from threads that may be asynchronously
* cancelled.
*
* @since release v2.1.0.
* @since release v2.2.0.
*
* @param facility_string The facility name to get the enum from.
*
Expand Down
2 changes: 1 addition & 1 deletion include/stumpless/severity.h
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
/* SPDX-License-Identifier: Apache-2.0 */

/*
* Copyright 2018-2022 Joel E. Anderson
* Copyright 2018-2023 Joel E. Anderson
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
Expand Down