Skip to content

Latest commit

 

History

History
260 lines (189 loc) · 13.3 KB

CONTRIBUTING.md

File metadata and controls

260 lines (189 loc) · 13.3 KB
Raw

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" 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," 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.

  4. 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,

    #define _TIOC 'T'
#define TCSANOW (_TIOC|14)

    should be reduced to

    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:

    #include <stdio.h>
#include <stdlib.h>
#include <termios.h>

int main(void)
{
    printf("TCSANOW = 0x%04X\n", TCSANOW);
    return EXIT_SUCCESS;
}

  5. 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. Many operating systems provide them, but some do not.)

  6. Make sure cargo build and cargo test for termios-rs both pass on the target platform.

  7. Optionally, test some projects that depend on termios-rs. Some popular projects that depend on termios-rs include:

When submitting a patch, please provide testing guidance. See the section, "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," 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." 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," 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" 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," 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:

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," 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, your operating system's manual pages, and internet searches are your best resources for termios-specific help.