thank you for taking the time to learn about contributing to sopht! here's all
the ways you can help:

# filing issues
this is by far the easiest way to contribute to the project: just use the
program and if you find any bugs or think of any enhancements, let me know. the
best way to reach me is via my sourcehut
[public inbox](https://lists.sr.ht/~layta/public-inbox). i'm also reachable at
[soonerorlayta@gmail.com](mailto:soonerorlayta@gmail.com) if you'd prefer to
contact me privately for any reason. additionally, feel free to send questions
and any other discussion about the program to this mailing list too.

# contributing code
if you don't have git send-email set up, follow the wonderful instructions at
[git-send-email.io](https://git-send-email.io/). next, clone the repo and set
the mailing list via:
```
git config sendemail.to "~layta/public-inbox@lists.sr.ht"
```
and your subject line via
```
git config format.subjectPrefix "PATCH sopht"
```

after that, you're ready to make patches! make the changes you wish to and send
your commits to the mailing list. see the below sections for a codemap and some
other guides to aid you in understanding the codebase.

# codemap
this codemap does its best to lay out *where* to find particular components in
the code, but it probably won't help you with everything! so please send an
email if you have questions that aren't answered here. additionally, see the
[readme](README.md) for a link to the project documentation, which is hosted on
docs.rs and gives a very navigable high-level view of the codebase and details
all associated functions for the structures listed below.

* [process.rs](src/process.rs) - lower level functionality for interacting with
child processes. implementation of the `Process` structure and the supplementary
`read_thread` function.
* [ipc.rs](src/ipc.rs) - implements sopht's IPC protocol. specifically the
`Connection` structure and utility functions `create_client_connection` and
`socket_file_path`
* [manager.rs](src/manager.rs) - functionality related to the process management
facilities of sopht. notably the `State` structure and its implementation, which
contains all server-side commands executable by the sopht client. also contains
the supporting structures `ManagedProcess`, `ExitStatus`, `ProcessStatus`,
`UpkeepInfo`, `RestartPolicy`. out of all these structures, `State` is the only
one that has associated functions. all other structures are generated by the
associated functions of `State`.
* [lib.rs](src/lib.rs) - module declarations, program-wide utility functions,
and the `Result`, `Error`, `Command`, `Response`, and `Message` types as well
as their trait implementations. the only program-wide utility function defined
here is `create_local_dirs`
* [sopht.rs](src/bin/sopht.rs) - implements the sopht client program.
responsible for argument parsing, determining the message to send, receiving the
response, and conveying it to the user. this file is also the source of the
usage/help string.
* [sophtd.rs](src/bin/sophtd.rs) - implements the sopht server. the server
implementation has a lot of responsibilities: setting signal handlers, receiving
and handling messages, creating the local socket itself, and periodically
calling upkeep by creating a manager thread.

# maintanence guide
this guide serves to keep all aspects of the project updated and tidy. when
contributing code to the project, please ensure that you look over this section
before making patches. (some of the items on this checklist are to keep me in
line more than anyone else ^_^)

- [ ] if necessary, update all in-code documentation local to where your changes
are. for example, if the interface of a particular function changed or it took
on an extra side-effect, its doc comment should *always* reflect that.
- [ ] add comments where your contributions might be unclear to others or you in
the future.
- [ ] if new functions/structures were added to a module, ensure that the
codemap is still accurate.
- [ ] be verbose and clear in your commit messages. if your editor tells you to
keep them below 50 or 72 characters, don't. write a concise title, but use the
description to its full potential.
- [ ] if the CLI interface changed, update the help message to explain the new
usage. currently, the project elects not to have help message generation when
we can just maintain good documentation.
- [ ] when creating a release, do the following
    1. ensure that the readme is up-to-date with the latest usage string,
    examples, links, and documentation. for the crates.io link, check that the
    next version is clear to be released (i.e not already taken on the site
    for some reason), then add a non-functional link to the readme linking to
    where the docs.rs page *will* be.
    2. ensure that the `Cargo.toml` file is up-to-date and contains the latest
    version.
    3. run `cargo clippy` and `cargo fmt` to lint and format your changes.
    4. commit any changes necessary from steps 1 and 2, then tag the latest
    commit with the next version.
    5. publish to crates.io (this will make the docs.rs link in step 1 start
    working), then push the update to source control.