Skip to content

Latest commit

 

History

History
176 lines (125 loc) · 11.5 KB

MAINTAINERS.md

File metadata and controls

176 lines (125 loc) · 11.5 KB
Raw

StrykerJS maintainer handbook

Introduction

We've written this document for:

  1. Active maintainers of StrykerJS
  2. Prospective maintainers of StrykerJS
  3. Anyone curious about how StrykerJS's maintainers maintain StrykerJS

The purpose of this document is to describe our processes. We want to avoid conflicts and confusion around "unwritten rules". In our opinion, the most straightforward way to address this is to write them down. This also happens to be the most straightforward way to change them!

Code of conduct

See Code of conduct

Contributor

This is the most important thing: You don't have to write code to be a contributor!

A "contributor" is any individual who has given back in some way to the project and its community. Contributions include (but are not limited to):

  1. Reporting bugs which follow the reporting guidelines
  2. Suggesting and debating enhancements that have wide applicability
  3. Helping others with Stryker-related questions on Slack, or other sites.
  4. Sending pull requests which fix bugs, improve documentation, improve developer experience, improve code quality, and/or implement requested enhancements
  5. Reviewing code on pull requests
  6. Providing design assets
  7. Posting a tutorial on a personal blog or blogging site
  8. Suggesting usages for project funds
  9. Organizing a "Stryker" event or workshop
  10. Spreading the love for mutation testing and test quality in general.
  11. Recruiting more contributors! Don't spam.
  12. Researching the user base, getting feedback, etc. Don't spam.

A contributor is usually a user as well, but this isn't a hard-and-fast rule. A contributor is also expected to adhere to the Code of conduct as a user would.

Maintainer

A maintainer has certain "rights" (or "permissions") to the StrykerJS project and other projects under the stryker-mutator organization. These rights come with increased responsibilities.

However, there is no expectation of a standard of technical ability to be a maintainer of StrykerJS. This doesn't imply a lack of technical oversight--every pull request will eventually be reviewed.

If you think you aren't experienced enough to maintain a project like StrykerJS, you are incorrect. The only requirements are the above responsibilities and a desire to help the project. It bears repeating:

You don't have to write code to be a maintainer!

A maintainer is synonymous with "Collaborator" and/or "Owner" in GitHub parlance.

The Responsibilities of a Maintainer

As a maintainer, you are expected to not just "follow" the code of conduct, but embody its values. Your public behavior, whether in the physical or virtual world, reflects upon the project and other maintainers.

If you don't understand the code of conduct, or why it exists, it is your responsibility to educate yourself. This does not imply the CoC is immutable.

Furthermore, a maintainer is a contributor who contributes regularly, or expresses a desire to do so. That could be every day--but it might be once a week, or even once a month. Your boss doesn't work here; contribute as often as you wish. We are all people with Real Lives, and for many of us, contributing to OSS is just a hobby!

Finally, a maintainer must help define what makes Stryker "Stryker". At a minimum, a maintainer must understand the current definition (if a maintainer is not interested in decision-making). Some of these questions include:

  • What's the scope of StrykerJS?
  • Where should we focus our efforts?
  • What's urgent, what can wait?
  • What can we break? What's off-limits?
  • What user feedback is valuable? What isn't?

As maintainers, we work together to learn about the nature of these questions. If we try hard enough, we even come to some answers!

A maintainer must also have 2FA enabled on their GitHub account.

The Rights of a Maintainer

You may choose to do zero or more of these at their discretion:

  1. Merge pull requests
  2. Modify issues (closing, adding labels, assigning them to other maintainers, etc.)
  3. Cancel builds, restart jobs, or otherwise interact with our CI server(s)
  4. CRUD operations on GitHub integrations
  5. Participate in the decision-making process

About "Owners"

Some maintainers will have full admin rights to the stryker-mutator organization and/or will have access to publish to npm.

  1. Those with publishing access are expected to use npm's 2FA.
  2. This level of access will be granted by the current owners to those maintainers who have earned the project's trust.
  3. Add new maintainers to the team.

Reaching decisions

StrykerJS follows a consensus-seeking decision-making process. In other words, all maintainers attempt to come to an agreement. If that fails, owners will decide.

Active maintainers will make an effort to solicit feedback from others before making important or potentially controversial decisions. Given the varying geographical distribution and availability of the maintenance team, we resolve to do the best we can to solicit feedback.

In other words, to have your opinion heard, participate regularly. The rest of the team won't wait on feedback that isn't necessarily forthcoming!

Communication

Maintainers will mainly gather in the stryker channel on slack. This is a public channel, and anyone can join.

Video conference (or audio) calls may happen on a regular or irregular basis, as schedules allow. This is mainly because we have Real Lives and time zones suck.

Working with Issues & Pull Requests

All new issues will need to be triaged, and pull requests must be examined. Maintainers must understand Semantic Versioning ("SemVer"), as StrykerJS follows it semi-strictly.

We’re also using conventional commits (or see summary here). This means that the commit message decides the next release version number as well as the annotation in the changelog. This why it is important to always squash merge PR’s and decide on a good commit message.

Some examples:

✅ A feature without breaking change.

feat(karma-runner): resolve local karma and ng version

Require karma or @angular/cli from the current working directory, instead of from @stryker-mutator/karma-runner/src/util.js (where the old requireModule function lived).

✅ Fix something in the docs (won’t appear in changelog)

docs(plugins): fix dead link

✅ A feature with a breaking change

feat(jest-runner): remove deprecated project types

Remove deprecated project types.

  • react --> create-react-app
  • react-ts --> create-react-app-ts

BREAKING CHANGE: Project types react and react-ts have been removed. Please use create-react-app and create-react-app-ts respectively

❌ Comment message has to be present tense

~~ feat(karma-runner): resolved local karma and ng version ~~

❌ Format issues:

~~ feat(karma-runner) resolved local karma and ng version ~~ ~~ feat resolved local karma and ng version (#2622) ~~

❌ Scope too vague

feat(stryker): allow for coverageAnalysis "all" in jest-runner

It is important to note that these message are not necessary when contributing a PR, only when squash merging them (we only care about commit messages on the master branch).

Once more: Only use squash merge to the master branch.

Commenting on Issues and Reviewing Pull Requests

All maintainers should be courteous and kind. Thank the external contributor for the pull request, even if it is not merged. If the pull request has been opened (and subsequently closed) without discussion in a corresponding issue, let them know that by creating an issue first, they could have saved wasted effort. Clearly and objectively explain the reasoning for rejecting any PR.

If you need more information on an issue, nicely ask the user to provide it. Remind them to use the issue/PR templates if they have not. If the user never gets around to it, the "stalebot" will close it eventually anyhow.

Reviewing Code

Use GitHub's code review features. Requesting a review from another maintainer may or may not actually result in a review; don't wait on it. If the PR cannot move forward without input from a certain maintainer, assign them to the PR. If you’re waiting on someone, send them a direct message on Slack.

The Part About Jerks

There will be jerks.

Rude or Entitled People

These are users who feel the StrykerJS project and its maintainers owe them time or support. This is incorrect.

However, this behavior is often indicative of someone who is "new" to open source. Many just don't know better. It is not your responsibility to educate them (again, you owe them nothing).

Here are some suggestions:

  1. If u mad, wait 20 minutes before writing a comment.
  2. "Kill them with kindness". Explain how they are presenting themselves; maybe link to a good article or two about it.
  3. Don't make it about "users vs. maintainers". Treat them like a potential future maintainer.
  4. Avoid adding to the drama. You could try to reach out privately; email may be in their GitHub profile. You will likely never hear from that individual again (problem solved)
  5. If an issue is getting out of control, lock it.
  6. If someone is repeatedly rude and does not correct their mistakes, you may ban them from participating in the stryker-mutator org. If you do not have permission to do so, contact someone who does (an "owner").

When do we release?

We release when we feel like it. However, we don’t want to overwhelm users with new versions. That’s why we’ve decided to release major versions a maximum of 2 times a year. Furthermore, we might decide to group features together, in order to not release multiple minor versions in a short period of time.

Scope of Stryker

The Stryker Mutator initiative consists of 3 main mutation testing frameworks:

  • StrykerJS (for JavaScript and friends)
  • Stryker.NET (for C# and maybe other .NET languages)
  • Stryker4s (for scala and maybe other JVM languages)

Since Stryker began only for JavaScript and friends, it started with the name "Stryker", but we since migrated to "StrykerJS".

The scope for StrykerJS is "JavaScript and friends". This includes all test frameworks and all babel parsable JavaScript languages. Some examples:

However, we only support languages parsable by babel, so too bad for coffee script or dart.