When you maintain an open-source project, you're constantly balancing the demands of your users with the constraints of your time and resources. One critical but often overlooked aspect of this balance is how you manage and communicate escalations. An effective escalation contract isn't just about what happens when things go wrong; it's about building trust and setting clear expectations with your community.
An "escalation contract" in this context is a set of defined procedures and commitments that dictate how severe issues will be handled, by whom, and within what timeframe. It's a formal or informal agreement that provides a path for users to get higher-level attention for critical problems and, crucially, for you to manage that attention sustainably. Without a clear contract, escalations can quickly devolve into chaos, leading to burnout for maintainers and frustration for users.
Why You Need an Escalation Contract
The primary reason to formalize your escalation process is to provide predictability. For users, it means understanding what to expect when they encounter a critical bug or security vulnerability. For maintainers, it means having a framework to prioritize and address urgent issues without constantly feeling overwhelmed or having to make ad-hoc decisions.
Key benefits include:
- Clear Expectations: Users know how to escalate and what the likely response time will be.
- Reduced Stress: Maintainers have a defined process, reducing the cognitive load of crisis management.
- Improved Trust: A transparent and consistently applied contract builds confidence in the project's stability and maintainer responsiveness.
- Efficient Resource Allocation: Critical issues receive appropriate attention without siphoning resources from less urgent but important work.
- Auditability: A documented process allows for review and improvement over time.
Defining Severity Levels
The foundation of any good escalation contract is a clear definition of issue severity. Without this, every issue might be perceived as critical by the reporter, leading to alert fatigue for maintainers. Establish a concise set of levels, typically 3-5, with distinct criteria.
For example:
- Severity 1 (Critical): Production system down, data loss, severe security vulnerability (e.g., RCE). No workaround. Immediate impact on core functionality.
- Severity 2 (High): Major functionality impaired, significant impact on operations, partial data loss, or high-risk security issue with a workaround. Degradation of core features.
- Severity 3 (Medium): Minor functionality impaired, inconvenient workaround exists, cosmetic issues, or low-risk security findings. Non-critical bugs.
- Severity 4 (Low): Feature requests, general questions, documentation improvements, minor UI glitches.
Each severity level should have an associated expected response time and resolution target. Be realistic about what you, as a maintainer, can commit to. It's better to under-promise and over-deliver than the reverse.
Communication Channels and Entry Points
How do users trigger an escalation? This needs to be explicitly defined. Relying solely on GitHub Issues might not be sufficient for critical problems, especially those with security implications.
Consider the following entry points:
- GitHub Issues: Standard for most bugs and feature requests. For higher severity, include a template section for the user to explicitly state the perceived severity and justification.
- Security Policy (SECURITY.md): For security vulnerabilities, direct users to a private disclosure channel, such as a dedicated email address (
security@yourproject.com) or a platform like HackerOne. - Dedicated Email/Form: For enterprise users or those who cannot use public channels for critical, non-security issues. This should be used sparingly and only for true escalations.
- Community Forums/Chat (e.g., Discord): While not ideal for formal escalation, these can be good for initial triage or for directing users to the correct formal channel.
Crucially, make sure these channels are clearly documented in your CONTRIBUTING.md or a dedicated ESCALATION.md file within your repository.
Defining Response and Resolution Targets
This is where the