6.1 KiB
Sudo for Windows Contributor's Guide
Below is our guidance for how to report issues, propose new features, and submit contributions via Pull Requests (PRs). Our philosophy is heavily based around understanding the problem and scenarios first, this is why we follow this pattern before work has started.
- There is an issue
- There has been a conversation
- There is agreement on the problem, the fit for Sudo for Windows, and the solution to the problem (implementation)
Filing an issue
Please follow this simple rule to help us eliminate any unnecessary wasted effort & frustration, and ensure an efficient and effective use of everyone's time - yours, ours, and other community members':
👉 If you have a question, think you've discovered an issue, would like to propose a new feature, etc., then find/file an issue BEFORE starting work to fix/implement it.
When requesting new features / enhancements, understanding problem and scenario around it is extremely important. Having additional evidence, data, tweets, blog posts, research, ... anything is extremely helpful. This information provides context to the scenario that may otherwise be lost.
- Don't know whether you're reporting an issue or requesting a feature? File an issue
- Have a question that you don't see answered in docs, videos, etc.? File an issue
- Want to know if we're planning on building a particular feature? File an issue
- Got a great idea for a new feature? File an issue
- Don't understand how to do something? File an issue
- Found an existing issue that describes yours? Great! upvote and add additional commentary / info / repro-steps / etc.
A quick search before filing an issue also could be helpful. It is likely someone else has found the problem you're seeing, and someone may be working on or have already contributed a fix!
Reporting Security Issues
Please do not report security vulnerabilities through public GitHub issues. Instead, please report them to the Microsoft Security Response Center (MSRC). See SECURITY.md for more information.
How to tell the Sudo team "this is an interesting thing to focus on"
Upvote the original issue by clicking its [+😊] button and hitting 👍 (+1) icon or a different one. This way allows us to measure how impactful different issues are compared to others. The issue with comments like "+1", "me too", or similar is they actually make it harder to have a conversation and harder to quickly determine trending important requests.
Localization issues
Please file localization issues, so our internal localization team can identify and fix them. However we currently don't accept community Pull Requests fixing localization issues. Localization is handled by the internal Microsoft team only.
Contributing code
As you might imagine, shipping something inside of Windows is a complicated process--doubly so for a security component. There is a lot of validation and paperwork that we don't really want to subject the community to. We want you to be able to contribute easily and freely, and to let us deal with the paperwork. We'll do our best to make sure this process is as seamless as possible.
To support the community in building new feature areas for Sudo for Windows, we're going to make extensive use of feature flags, to conditionally add new features to Sudo for Windows.
When contributing to Sudo for Windows, we will treat "bugfixes" and "features" separately. Bug fixes can be merged into the codebase freely, so long as they don't majorly change existing behaviors. New features will need to have their code guarded by feature flag checks before we can accept them as contributions.
As always, filing issues on the repo is the best way to have the team evaluate
if the change you're proposing would be considered a "bug fix" or "feature"
work. We will indicate which is which using the Issue-Bug and
Issue-Feature/Issue-Task labels. These labels are intended to be informative,
and may change throughout the lifecycle of a discussion.
We'll be grouping sets of feature flags into different "branding"s throughout the project. These brandings are as follows:
- "Inbox": These are features that are included in the version of sudo that ships with Windows itself.
- "Stable": Features that ship in stable versions of sudo released here on GitHub and on WinGet.
- "Dev": The least stable features, which are only built in local development builds. These are for work-in-progress features, that aren't quite ready for public consumption
All new features should be added under the "Dev" branding first. The core team will then be responsible for moving those features into the appropriate branding as we get internal signoffs. This will allow features to be worked on continually in the open, while we slowly roll them into the OS product. We unfortunately cannot provide timelines for when features will be able to move from Stable into Inbox. Historical data showing that a feature has a track record of being stable and secure is a great way for us to justify any particular feature's inclusion into the product.
If you're ready to jump in, head on over to Building.md to get started.
Repo Bot
The team triages new issues several times a week. During triage, the team uses labels to categorize, manage, and drive the project workflow.
We employ a bot engine to help us automate common processes within our workflow.
We drive the bot by tagging issues with specific labels which cause the bot engine to close issues, merge branches, etc. This bot engine helps us keep the repo clean by automating the process of notifying appropriate parties if/when information/follow-up is needed, and closing stale issues/PRs after reminders have remained unanswered for several days.
Therefore, if you do file issues, or create PRs, please keep an eye on your GitHub notifications. If you do not respond to requests for information, your issues/PRs may be closed automatically.
Thank you
Thank you in advance for your contribution!