-
-
Notifications
You must be signed in to change notification settings - Fork 236
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.
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 maintainer 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.
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
For small changes, such as fixing a spelling error in documentation using the browser, a temporarily branch can be created and deleted once the PR is merged.
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
When you want to open an discussion, do it in a separate issue.
- Create a new issue
- Put links to the issues/comments you want to discuss
- 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.
This team has write access to all repos, but don't push directly. See "Self merging".
This is a team reserved in case for the event somebody should not have write access, for some unknown reason. There is no role associated with this team, nor should be in the case multiple people are added to this team for different reasons.
This team has permissions to create repos. There is no upper limit of people that can be added to this group, but they should have a reason to need the permissions.
There is no special role or tasks required. The Piston project uses informal and practical organization depending on the need and people available.
The Owner team under PistonDevelopers have usually one task: To add people to the Admin group when they need the permissions. There is usually one person doing this task approximately 20 times a year.
Risk estimates recommends 3-5 people.
The secondary task is being the last resort if some things go wrong. In the event of all these people being in a single location, it is recommended adding another person just in case.
When selecting some other owner, pick people who have been active for several months (longer is better). The owner team has no special role besides keeping the Piston project running through these tasks. All other problems must be opened as issues.