Policy

We think of policies as recommended practice but no strict rules. Policies are created using analysis or decision in favor of maintainers, when there is a problem or things could run more smoothly.

• Analysis is the best method to make decisions
• When there is doubt of what to do, we tend to lend strongly in favor of maintainers of the individual project, since they are the people who probably know the problem, and they work on projects to pursue their personal goals
• We are part of a greater community, and building the community means the community as a whole
• The policies we make are for the Piston project only and should be addressing the individual problems

Therefore, policies are not community related, but addresses the practical issues of people who work under PistonDevelopers.

Maintainers

Any person can be a maintainer who contributes actively to a project. A project can have, or ideally should have, multiple maintainers.

• The informal definition of a maintainer is "People who work actively on a project". Sometimes people do not wish to take a maintainer role explicitly even when contributing actively. However, when it comes to decide the direction for a project, they still have as much power proportional to the amount they contribute.
• If a maintainer is not active for a long period of time, anyone else are free to step in as maintainer, but this requires active contribution. The period of time depends on the stability and feature completeness of the library.
• Maintainer roles are highly informal and uses social interactions to form. There is no official appointment of maintainers, and people are free to take on the role themselves.
• It is expected that big design decisions are followed by a "design rationale" as an issue labeled "information". This is to ensure that people can later track down the ideas.
• Being a maintainers does not mean you have to follow up a project every day. You can take free whenever you want, without asking. Everybody have write access, so there are always people who can step in if there is a problem.

Work against your fork

When working on a new feature, it is a good idea to use a separate branch on your fork. This makes branches unnecessary on the PistonDevelopers repo, in most cases.

Working directly against PistonDevelopers is associated with larger risks of doing mistakes. It also makes it harder for other people to follow the changes.

• Do not push directly to PistonDevelopers
• Use a branch on your fork and open PRs

Self merging

Most PRs deal with already planned issues, and are often done by people who know what they are doing. However, even if you know what you are doing, there is a chance that you still make bad decisions. The usual way of getting rid of bad decisions is to review PRs.

Estimations shows that on average, given that people know what they are doing, then review is mostly wasted time. See https://github.com/PistonDevelopers/piston/issues/674

Therefore, if you know what you are doing, then self merging is encouraged.

There are ways that we can increase the chance that we know what we are doing, to minimize bad decisions:

• Plan as much as possible upfront
• Break it down into easy tasks
• Wait with implementing for some time
• Collect information to arrive at good designs early
• Test changes by override dependency locally with Cargo

These tasks are designed to separate the thinking part from the doing part. We want to spend more brain cycles on planning and fewer brain cycles on implementing.

If we do lots of review, then we waste both brain cycles and time, which could go into planning.

When there is a perception that bad decisions occur frequently and wastes time, remember the following:

• The time waiting for review is saved
• Frequent bad decisions might mean something is wrong with the planning
• Some bad decisions takes longer time to fix, but what counts is the total saved time
• Fixing merged changes is quicker and less error prone than fixing forked changes

Discussions

When you want to open an discussion, do it in a separate issue.

1. Create a new issue
2. Put links to the issues/comments you want to discuss
3. Use the "Discussion" label

Don't post comments on issues that are irrelevant to the thing you want to discuss, when there is no label "Discussion". This is because the labels are the way people control their workflow, and it is a signal when discussion is wanted and when it gets in the way. If you think an issue should be discussed, then you can activate the label "Discussion", but opening an issue is the preferred way. It is important to maintain a space where maintainers and people working on the project can control, and the label system is the way we do this.