From fd91097055f095fdd827ef8751d9534f59a89404 Mon Sep 17 00:00:00 2001 From: Tavian Barnes Date: Sat, 16 Dec 2023 12:47:45 -0500 Subject: docs: Rename HACKING to CONTRIBUTING So that GitHub recognizes it. --- README.md | 4 ++-- docs/CONTRIBUTING.md | 61 ++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/HACKING.md | 61 ---------------------------------------------------- docs/USAGE.md | 8 +++---- 4 files changed, 67 insertions(+), 67 deletions(-) create mode 100644 docs/CONTRIBUTING.md delete mode 100644 docs/HACKING.md diff --git a/README.md b/README.md index a7ca335..79ffe65 100644 --- a/README.md +++ b/README.md @@ -9,13 +9,13 @@ Code coverage -**[Features]   •   [Installation]   •   [Usage]   •   [Building]   •   [Hacking]   •   [Changelog]** +**[Features]   •   [Installation]   •   [Usage]   •   [Building]   •   [Contributing]   •   [Changelog]** [Features]: #features [Installation]: #installation [Usage]: /docs/USAGE.md [Building]: /docs/BUILDING.md -[Hacking]: /docs/HACKING.md +[Contributing]: /docs/CONTRIBUTING.md [Changelog]: /docs/CHANGELOG.md diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 0000000..099157d --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,61 @@ +Contributing to `bfs` +===================== + +License +------- + +`bfs` is licensed under the [Zero-Clause BSD License](https://opensource.org/licenses/0BSD), a maximally permissive license. +Contributions must use the same license. + +Individual files contain the following tag instead of the full license text: + + SPDX-License-Identifier: 0BSD + +This enables machine processing of license information based on the SPDX License Identifiers that are available here: https://spdx.org/licenses/ + + +Implementation +-------------- + +`bfs` is written in [C](https://en.wikipedia.org/wiki/C_(programming_language)), specifically [C17](https://en.wikipedia.org/wiki/C17_(C_standard_revision)). +You can get a feel for the coding style by skimming the source code. +[`main.c`](/src/main.c) contains an overview of the rest of source files. +A quick summary: + +- Tabs for indentation, spaces for alignment. +- Most types and functions should be namespaced with `bfs_`. + Exceptions are made for things that could be generally useful outside of `bfs`. +- Error handling follows the C standard library conventions: return a nonzero `int` or a `NULL` pointer, with the error code in `errno`. + All failure cases should be handled, including `malloc()` failures. +- `goto` is not considered harmful for cleaning up in error paths. + + +Tests +----- + +`bfs` includes an extensive test suite. +See the [build documentation](BUILDING.md#testing) for details on running the tests. + +Test cases are grouped by the standard or `find` implementation that supports the tested feature(s): + +| Group | Description | +|---------------------------------|---------------------------------------| +| [`tests/posix`](/tests/posix) | POSIX compatibility tests | +| [`tests/bsd`](/tests/bsd) | BSD `find` features | +| [`tests/gnu`](/tests/gnu) | GNU `find` features | +| [`tests/common`](/tests/common) | Features common to BSD and GNU `find` | +| [`tests/bfs`](/tests/bfs) | `bfs`-specific tests | + +Both new features and bug fixes should have associated tests. +To add a test, create a new `*.sh` file in the appropriate group. +Snapshot tests use the `bfs_diff` function to automatically compare the generated and expected outputs. +For example, + +```bash +# posix/something.sh +bfs_diff basic -name something +``` + +`basic` is one of the directory trees generated for test cases; others include `links`, `loops`, `deep`, and `rainbow`. + +Run `./tests/tests.sh posix/something --update` to generate the reference snapshot (and don't forget to `git add` it). diff --git a/docs/HACKING.md b/docs/HACKING.md deleted file mode 100644 index 0763fda..0000000 --- a/docs/HACKING.md +++ /dev/null @@ -1,61 +0,0 @@ -Hacking on `bfs` -================ - -License -------- - -`bfs` is licensed under the [Zero-Clause BSD License](https://opensource.org/licenses/0BSD), a maximally permissive license. -Contributions must use the same license. - -Individual files contain the following tag instead of the full license text: - - SPDX-License-Identifier: 0BSD - -This enables machine processing of license information based on the SPDX License Identifiers that are available here: https://spdx.org/licenses/ - - -Implementation --------------- - -`bfs` is written in [C](https://en.wikipedia.org/wiki/C_(programming_language)), specifically [C17](https://en.wikipedia.org/wiki/C17_(C_standard_revision)). -You can get a feel for the coding style by skimming the source code. -[`main.c`](/src/main.c) contains an overview of the rest of source files. -A quick summary: - -- Tabs for indentation, spaces for alignment. -- Most types and functions should be namespaced with `bfs_`. - Exceptions are made for things that could be generally useful outside of `bfs`. -- Error handling follows the C standard library conventions: return a nonzero `int` or a `NULL` pointer, with the error code in `errno`. - All failure cases should be handled, including `malloc()` failures. -- `goto` is not considered harmful for cleaning up in error paths. - - -Tests ------ - -`bfs` includes an extensive test suite. -See the [build documentation](BUILDING.md#testing) for details on running the tests. - -Test cases are grouped by the standard or `find` implementation that supports the tested feature(s): - -| Group | Description | -|---------------------------------|---------------------------------------| -| [`tests/posix`](/tests/posix) | POSIX compatibility tests | -| [`tests/bsd`](/tests/bsd) | BSD `find` features | -| [`tests/gnu`](/tests/gnu) | GNU `find` features | -| [`tests/common`](/tests/common) | Features common to BSD and GNU `find` | -| [`tests/bfs`](/tests/bfs) | `bfs`-specific tests | - -Both new features and bug fixes should have associated tests. -To add a test, create a new `*.sh` file in the appropriate group. -Snapshot tests use the `bfs_diff` function to automatically compare the generated and expected outputs. -For example, - -```bash -# posix/something.sh -bfs_diff basic -name something -``` - -`basic` is one of the directory trees generated for test cases; others include `links`, `loops`, `deep`, and `rainbow`. - -Run `./tests/tests.sh posix/something --update` to generate the reference snapshot (and don't forget to `git add` it). diff --git a/docs/USAGE.md b/docs/USAGE.md index 86eef87..3efdee0 100644 --- a/docs/USAGE.md +++ b/docs/USAGE.md @@ -18,7 +18,7 @@ $ bfs ./completions/bfs.zsh ./docs/BUILDING.md ./docs/CHANGELOG.md -./docs/HACKING.md +./docs/CONTRIBUTING.md ./docs/USAGE.md ./docs/bfs.1 ... @@ -53,7 +53,7 @@ $ bfs -name '*.md' ./README.md ./docs/BUILDING.md ./docs/CHANGELOG.md -./docs/HACKING.md +./docs/CONTRIBUTING.md ./docs/USAGE.md ``` @@ -64,7 +64,7 @@ When you put multiple expressions next to each other, both of them must match: ```console $ bfs -name '*.md' -name '*ING*' ./docs/BUILDING.md -./docs/HACKING.md +./docs/CONTRIBUTING.md ``` This works because the expressions are implicitly combined with *logical and*. @@ -84,7 +84,7 @@ $ bfs -name '*.md' -or -name 'bfs.*' ./completions/bfs.zsh ./docs/BUILDING.md ./docs/CHANGELOG.md -./docs/HACKING.md +./docs/CONTRIBUTING.md ./docs/USAGE.md ./docs/bfs.1 ``` -- cgit v1.2.3