Contributing guidelines and project status

2 files changed, 276 insertions, 1 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..ec4bb1a
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,260 @@
+# Contributing
+
+Termios is a pervasive API on Unix-like systems. One person can't possibly be an expert is all of
+the platforms that `termios-rs` may want to target. This document provides guidelines for how we can
+work together as complete strangers while maintaining a high standard for quality.
+
+## General Guidelines
+
+* Above all, don't be a jerk. You won't get what you want that way.
+
+* Please try to keep discussion focused on improving this project. Don't use the issue tracker to
+  promote other projects. A brief mention of another project as it relates to the development of
+  this project is okay. This also isn't the place for political activism.
+
+* Remember that nobody is paid to work on this project. There are no contractual obligations, and no
+  promises have been made. Maintainers have friends, family, kids, hobbies, and responsibilities
+  outside of this project. Please calibrate your expectations accordingly.
+
+* Maintainers have the final say. The maintainers are not your co-workers and they don't work for
+  you. Please calibrate your expectations accordingly.
+
+* Avoid "+1" or similar comments. Try to find a more constructive way to move the project forward. A
+  comment with how you've tested a patch and your results adds more value than "+1" while serving
+  the same purpose. See "[Reviewing Patches](#reviewing-patches)" below for ideas of how you can
+  help.
+
+* If you want to see something get done, the best way is to roll up your sleeves and do it. Read
+  below for details on how you can help.
+
+## Moderating
+
+Some people just don't know how to behave on the internet. Unfortunately, this is one of the leading
+causes for maintainers to walk away from their projects. That makes moderating user behavior one of
+most important things that any mentally-stable adult can do to contribute to an open source project.
+Being a moderator doesn't require being blessed with a special status. Anyone can help.
+
+If you see anyone being rude, acting with a sense of entitlement, putting down others or their work,
+arguing in bad faith, or in any other way making the project an unpleasant place to spend one's
+time, please call out the bad behavior. As a maintainer, it helps to see that we're not on our own
+when dealing with bad behavior.
+
+This includes enforcing theses contributing guidelines. If you see patches or issues that don't
+appear to be based on these guidelines, please ask the submitter to provide the missing details.
+
+If you'd prefer to email me privately about someone's behavior, please do so. My email can be found
+in public profiles or the project's commit history.
+
+## Adding Support for New Platforms
+
+The currently supported platforms are listed in the README. If an operating system and architecture
+aren't listed there, it means that nobody has confirmed that `termios-rs` works on that platform.
+The following sections describe different ways that one can help add support for a new platform.
+The guidelines in this section are meant to increase the chances that a patch can land smoothly the
+first time that a maintainer reviews it.
+
+### Sending Patches
+
+Patches should be based on reading the C header file `termios.h`. This is often located at
+`/usr/include/termios.h` or `/usr/include/sys/termios.h`. You may have to install a package to get
+the header files.
+
+IMPORTANT: Please do not count on a platform being so similar to another platform that you can just
+copy the definitions. I'm pretty sure every patch that has been submitted that way has proven the
+assumption to be wrong. That just wastes everyone's time. Don't submit patches without testing them.
+
+To make a patch for a new platform, you'll need to setup the target platform with a working Rust
+compiler and `termios.h` header file. Sometimes a working C compiler can help, too. Please take note
+of the steps you use to setup your platform so that you can provide testing guidance when submitting
+your patch. See "[Testing Guidance](#testing-guidance)," for details.
+
+1.  Start by creating a new file in `src/os/` for the target platform. To keep things consistent,
+    pick a name that matches the value of Rust's `target_os` configuration variable, e.g.,
+    `src/os/freebsd.rs`.
+
+2.  Adjust the `use` and `mod` items in `src/os/mod.rs`.
+
+3.  Add an example to the doctest under "OS-Specific Extensions" in `src/lib.rs`. `cargo test` won't
+    pass without it.
+
+3.  Read through the `termios.h` header file and transliterate it to Rust. Someone reading through
+    the  Rust file and C header file side-by-side should be able to easily verify that they produce
+    the same values. That means:
+
+    * Values in the Rust file should be defined in the same radix (decimal, octal, hexidecimal) as
+      the C header file.
+
+    * Definitions should appear roughly in the same order that they appear in the C header file.
+      Please try to keep them grouped similar to other platforms. That means keeping `c_cc` character
+      indexes together, `c_iflag` bits together, `c_oflag` bits together, etc. But within each of
+      those groups, match the order of the C header file.
+
+    One exception to transliterating the header file is to expand macros to their literal value.
+    For example,
+
+    ```c
+    #define _TIOC 'T'
+    #define TCSANOW (_TIOC|14)
+    ```
+
+    should be reduced to
+
+    ```rust
+    pub const TCSANOW: c_int = 0x005E;
+    ```
+
+    In this case, simplicity is the overriding concern. This is where having a C compiler on the
+    target platform can help. To avoid error in computing the literal value, you can let a C
+    compiler do it for you:
+
+    ```c
+    #include <stdio.h>
+    #include <stdlib.h>
+    #include <termios.h>
+
+    int main(void)
+    {
+        printf("TCSANOW = 0x%04X\n", TCSANOW);
+        return EXIT_SUCCESS;
+    }
+    ```
+
+4.  Check which of the functions in `src/ffi.rs` the target platform implements (look for them in
+    `termios.h`). If the target platform doesn't implement one or more of them, adjust the `#[cfg]`
+    items in `src/ffi.rs` to use the fallback imlementations. (`cfmakeraw()` and `cfsetspeed()` are
+    technically not part of the [POSIX standard for termios][posix]. Many operating systems provide
+    them, but some do not.)
+
+5.  Make sure `cargo build` and `cargo test` for `termios-rs` both pass on the target platform.
+
+6.  Optionally, test some projects that depend on `termios-rs`. Some popular projects that depend on
+    `termios-rs` include:
+
+    * [`serial-rs`](https://github.com/dcuddeback/serial-rs)
+
+    * [`bat`](https://github.com/sharkdp/bat)
+
+When submitting a patch, please provide testing guidance. See the section, "[Testing
+Guidance](#testing-guidance)," for details.
+
+### Reviewing Patches
+
+The best way to help land an existing patch is to review it. If you review a patch, please leave a
+review comment on its submission so that maintainers can see how many eyes have looked at a patch.
+If you don't comment, we won't know. And commenting on a patch with what you've done to review and
+test it is much more helpful than "+1" comments.
+
+See the section, "[Testing](#testing)," for details on how to test a patch. If you tested something
+that others hadn't, such as a different version of an operating system or a different reverse
+dependency, please comment with details of what you tested and the results.
+
+Check the patch for conformance to the guidelines described in "[Sending
+Patches](#sending-patches)." Feel free to add line comments where you spot anything that looks
+incorrect. Whether or not you spot any errors, please leave a review comment so that maintainers
+know how much peer-review a patch has received.
+
+Make sure that the patch was submitted with sufficient testing guidance. See the section, "[Testing
+Guidance](#testing-guidance)," for details. If the guidance seems incomplete, ask the submitter to
+provide additional details or add the relevant details yourself if you can. If you have an
+alternative way of testing, feel free to provide those details according to the "[Testing
+Guidance](#testing-guidance)" section.
+
+### Testing
+
+If you're interested in a different architecture of an existing operating system, it may be just a
+matter of testing the new architecture. Or if you see a patch for a platform you're interested in,
+you can help test that patch, too.
+
+To test platform support, you'll need to have a working Rust compiler on the target platform, and
+you'll need the C header files for `termios`. A working C compiler can help, too.
+
+1.  Find the Rust definitions for the platform you're testing. This will be in
+    `src/os/{platform}.rs`, e.g., `src/os/freebsd.rs` for FreeBSD.
+
+2.  Find the C header file for your platform. This is often located at `/usr/include/termios.h` or
+    `/usr/include/sys/termios.h`. On some platforms, you may have to install a package to get the
+    header files. (If so, please report which package.)
+
+3.  Verify that the definitions in the Rust code match the definitions from the C header file. If
+    reviewing a new patch submission, verify that the values are defined in the same radix as the C
+    header file and are defined in roughly the same order. If the submitter followed the guidelines
+    in "[Sending Patches](#sending-patches)," this step should go smoothly.
+
+4.  Verify that `cargo build` and `cargo test` for `termios-rs` both succeed on the target platform.
+
+5.  Optionally, test some projects that depend on `termios-rs`. Some popular projects that depend on
+    `termios-rs` include:
+
+    * [`serial-rs`](https://github.com/dcuddeback/serial-rs)
+
+    * [`bat`](https://github.com/sharkdp/bat)
+
+Please report back on your findings. Knowing that a platform has had several sets of eyes looking at
+it is helpful.
+
+If you tested a new architecture for an already-supported operating system and everything appears
+correct, please submit a patch to add the architecture to the list of supported platforms in the
+README. When submitting such a patch, please describe what you tested, including any reverse
+dependencies, and provide any testing guidance you can for the maintainers. See the section,
+"[Testing Guidance](#testing-guidance)," for details.
+
+### Testing Guidance
+
+Before landing a patch, a maintainer will need to verify the patch on the target platform. That
+means a maintainer will need to setup a virtual machine running the target platform, setup SSH
+access, and install a working Rust compiler, `termios.h` header files, and possibly a C compiler.
+Any instructions you can provide to help a maintainer or other testers through those steps will help
+land the patch quicker. Try to be as complete and precise as possible, including full commands where
+appropriate.
+
+Some helpful tips could include:
+
+  * How to obtain installation media for the target platform. Some platforms are made up of many
+    distributions. Some less popular platforms may not have official Rust support or may have
+    recently gained Rust support in their latest nightly snapshot. If this matters, please point to
+    the release channel that provides the greatest chance of success of getting things working. At
+    the very least, just tell us what you used (which distribution, version, and release channel, if
+    applicable).
+
+  * Any special steps to setup a virtual machine. How should the virtual hardware be setup? For less
+    popular architectures, providing specific commands to use with QEMU or libvirt would be ideal.
+    If you only have instructions for other hypervisors, go ahead and provide them.
+
+  * How to setup and configure SSH access. What packages need to be installed? Is there a
+    configuration file that needs to be edited?
+
+  * How to install Rust and Cargo. Does `rustup` work on the target platform? Is Rust in the
+    platform's package manager? What's the package name? Does it need to be installed from an
+    unofficial channel?
+
+  * How to install the termios header files and a C compiler. Usually these are just packages that
+    needs to be installed. Which packages?
+
+The easier it is for a maintainer to verify a patch, the easier it will be for a maintainer to land
+the patch. :)
+
+### Requesting Support for New Platforms
+
+Platforms that have been tested are listed in the README. Any platform that implements the termios
+API is fair game to add to `termios-rs`, so there is implicitly an open ticket for any platform not
+listed in the README. If you're interested in a platform that isn't listed in the README, you may
+open a ticket to request support, but that won't change much. Someone will need to roll up their
+sleeves and do the work to support it. At most, a ticket provides a place to coordinate who's
+working on support for a platform.
+
+## Other Requests
+
+There may occasionally be a small enhancement worth considering, like adding a trait implementation
+or adding to the documentation. Go ahead and open tickets or send patches for small enhancements.
+
+Most other requests are probably out of scope. `termios-rs` aims to be a very stable, low-churn
+library with wide platform support. There's little value in constantly refactoring it, adding
+dependencies, or debating design patterns.
+
+This also isn't the place to ask for help with general programming questions or how to use the
+termios API. The scope of this project is to provide the Rust bindings for the termios API. The
+termios API itself is standardized by POSIX and provided by your operating system. The [POSIX
+standard][posix], your operating system's manual pages, and internet searches are your best
+resources for termios-specific help.
+
+[posix]: https://pubs.opengroup.org/onlinepubs/009695399/basedefs/termios.h.html
diff --git a/README.md b/README.md
index 66eb03f..8b3824a 100644
--- a/README.md
+++ b/README.md
@@ -7,7 +7,17 @@ converts integer return values to `std::io::Result` to indicate success or failu
 
 * [Documentation](http://dcuddeback.github.io/termios-rs/termios/)
 
-## Dependencies
+## Project Status
+
+This is a very low-maintenance project. The termios API is decades old. This isn't an area that you
+should expect to see daily commits, so don't be put off if you don't see commits for several years.
+This just means that the project is stable. That's a good thing. :)
+
+If, however, you see old patches that you'd like to see land, please see
+[`CONTRIBUTING.md`](CONTRIBUTING.md) to see how you can help.
+
+## Dependencies & Compatibility
+
 In order to use the `termios` crate, you must have a native `libc` library that implements the
 termios API. This should be available on any Unix operating system. This library contains the
 termios definitions for the following platforms:
@@ -21,7 +31,11 @@ termios definitions for the following platforms:
 * DragonFly BSD (x86_64)
 * illumos (x86_64)
 
+If you're interested in a platform that's not listed here, please see
+[`CONTRIBUTING.md`](CONTRIBUTING.md) to see how you can help.
+
 ## Usage
+
 Add `termios` as a dependency in `Cargo.toml`:
 
 ```toml
@@ -63,6 +77,7 @@ fn setup_fd(fd: RawFd) -> io::Result<()> {
 * [qbit](https://github.com/qbit)
 
 ## License
+
 Copyright © 2015 David Cuddeback
 
 Distributed under the [MIT License](LICENSE).