Updates to documentation (#100)
* Getting started section refactored into separate document * Added Issue guide doc * Added Quick Links into README * Scoped .NET Core 3.0 work to parity with WinForms for .NET Framework * Added security bugs reporting info * Wording changes
This commit is contained in:
Karel Zikmund
GitHub
Родитель
997bd514c5
Коммит
d886b6dcef
|
|
@ -0,0 +1,31 @@
|
|||
# Getting started with WinForms for .NET Core
|
||||
|
||||
## Installation
|
||||
|
||||
Choose one of these options:
|
||||
|
||||
1. Official public preview [.NET Core 3.0 SDK Preview 1](https://www.microsoft.com/net/download), or
|
||||
2. [Daily build](https://aka.ms/netcore3sdk) (for more installer options see [dotnet/code-sdk repo](https://github.com/dotnet/core-sdk)).
|
||||
|
||||
To use the **WinForms designer**, you'll need Visual Studio. We recommend [Visual Studio 2019 Preview 1](https://visualstudio.microsoft.com/downloads/).
|
||||
Select the **.NET desktop development** workload with the options: **.NET Framework 4.7.2 development tools** and **.NET Core 3.0 development tools**.
|
||||
|
||||
## Creating new applications
|
||||
|
||||
You can create a new WinForms application with `dotnet new` command, using the new templates for WinForms.
|
||||
|
||||
In your favorite console run:
|
||||
```cmd
|
||||
dotnet new winforms -o MyWinFormsApp
|
||||
cd MyWinFormsApp
|
||||
dotnet run
|
||||
```
|
||||
|
||||
## Porting existing applications
|
||||
|
||||
To port your existing WinForms application from .NET Framework to .NET Core 3.0, refer to our [porting guidelines](porting-guidelines.md).
|
||||
|
||||
## Samples
|
||||
|
||||
Check out the .NET Core 3.0 WinForms [samples](https://github.com/dotnet/samples/tree/master/windowsforms)
|
||||
for HelloWorld examples and more advanced scenarios.
|
||||
|
|
@ -0,0 +1,114 @@
|
|||
# Issue Guide
|
||||
|
||||
This page outlines how WinForms team thinks about and handles issues.
|
||||
For us, issues on GitHub represent actionable work that should be done at some future point.
|
||||
It may be as simple as a small product or test bug or as large as the work tracking the design of a new feature.
|
||||
|
||||
We will keep issues open even if the WinForms team internally has no plans to address them in an upcoming release, as long as we believe they are in line with our direction.
|
||||
|
||||
|
||||
|
||||
## How to file issues
|
||||
|
||||
You can help us streamline our response time to your feedback and ideas by filing high-quality reports.
|
||||
|
||||
### High-quality bugs
|
||||
|
||||
In general, try to be specific. Get straight to the main point. Leave additional details, options and alternatives to the end (hint: separate them visually). Don't write too long bug reports, unless you have to.
|
||||
|
||||
* Include minimal repro in your bug if at all possible (chop off dependencies, remove as much code as possible). If it is not possible, say why.
|
||||
* Note: Yes, it may take some time to minimize a repro from your larger app - but that is exactly what we would do in most cases anyway. Issues with clear small repros are easier for us to reproduce/investigate and therefore have higher chance to be addressed quickly.
|
||||
* Include callstacks, symptom description, or what is the difference between actual and expected behavior.
|
||||
|
||||
### High-quality features and API suggestions
|
||||
|
||||
Provide clear description of your suggestion. Explain scenarios in which it would be helpful and why (motivation).
|
||||
Ideally, assume that the reader has minimal knowledge and experience with writing apps/libraries that would benefit from the feature.
|
||||
|
||||
For API suggestions, check [API review process](https://github.com/dotnet/corefx/blob/master/Documentation/project-docs/api-review-process.md), especially examples of [good API proposals](https://github.com/dotnet/corefx/issues/271).
|
||||
|
||||
|
||||
|
||||
## Labels
|
||||
|
||||
We use GitHub [labels](https://github.com/dotnet/winforms/labels) on our issues in order to classify them. We have the following categories per issue:
|
||||
|
||||
* **Issue Type**: These labels classify the type of issue. We use the following types:
|
||||
* [api-suggestion](https://github.com/dotnet/winforms/labels/api-suggestion): Issues which would add new APIs (see [API Review process](https://github.com/dotnet/corefx/blob/master/Documentation/project-docs/api-review-process.md) for details).
|
||||
* Note: WinForms API process is not finalized yet. We may need to add additional UI-specific steps to it (e.g. accessibility review). Expect finalized API review version post-3.0 when we will be ready to take new APIs.
|
||||
* [bug](https://github.com/dotnet/winforms/labels/bug), [enhancement](https://github.com/dotnet/winforms/labels/enhancement), [test-bug](https://github.com/dotnet/winforms/labels/test-bug), [test-enhancement](https://github.com/dotnet/winforms/labels/test-enhancement), [question](https://github.com/dotnet/winforms/labels/question), [documentation](https://github.com/dotnet/winforms/labels/documentation): See [label description](https://github.com/dotnet/winforms/labels) for details.
|
||||
* **Other**:
|
||||
* [up-for-grabs](https://github.com/dotnet/winforms/labels/up-for-grabs): Smaller sections of work which we believe are well scoped. These sorts of issues are a good place to start if you are new. Anyone is free to work on these issues.
|
||||
* [needs-more-info](https://github.com/dotnet/winforms/labels/needs-more-info): Issues which need more information to be actionable. Usually this will be because we can't reproduce a reported bug. We'll close these issues after a little bit if we haven't gotten actionable information, but we welcome folks who have acquired more information to reopen the issue.
|
||||
* [tenet-compatibility](https://github.com/dotnet/winforms/labels/tenet-compatibility): Incompatibility between relesed versions or with WinForms for .NET Framework.
|
||||
|
||||
|
||||
|
||||
## Milestones
|
||||
|
||||
We use [milestones](https://github.com/dotnet/corefx/milestones) to prioritize work for each upcoming release.
|
||||
|
||||
* **3.0** milestone work is focused on parity with WinForms for .NET Framework. We do not plan to take contributions or address issues that are not unique to WinForms on .NET Core in 3.0 release. For example:
|
||||
* Bugs which are present on both WinForms platforms (for .NET Core and .NET Framework) will be put into **Future** milestone and will be reviewed and prioritized after 3.0 final release.
|
||||
* Requests for new APIs and features will be put into **Future** milestone and will be reviewed and prioritized after 3.0 final release.
|
||||
* **Future** milestone tracks all potential future work (which may or may not happen). When we are done with 3.0 release, we will move some of these issues into the next immediate milestone.
|
||||
* Please do not start discussions about next post-3.0 milestone until we are close to final 3.0 release. If you want to express your opinion on prioritization, please [upvote first post of the issue](#upvotes-on-issues) instead.
|
||||
|
||||
|
||||
|
||||
## Assignee
|
||||
|
||||
We assign each issue to assignee, when the assignee is ready to pick up the work and start working on it.
|
||||
If the issue is not assigned to anyone and you want to pick it up, please say so - we will assign the issue to you.
|
||||
If the issue is already assigned to someone, please coordinate with the assignee before you start working on it.
|
||||
|
||||
|
||||
|
||||
## Upvotes on issues
|
||||
|
||||
Upvotes on first post of each issue are useful hint for our prioritization.
|
||||
We can [sort issues by number of upvotes](https://github.com/dotnet/winforms/issues?q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc) and we will review the top list on regular basis.
|
||||
|
||||
|
||||
|
||||
## Escalations
|
||||
|
||||
If you think some issue or PR is not getting the right attention, or if you notice some [Code of Conduct](https://dotnetfoundation.org/code-of-conduct) violation we might miss,
|
||||
you can escalate to WinForms team by tagging some of us (e.g. [@merriemcgaw](https://github.com/merriemcgaw), [@karelz](https://github.com/karelz)). Please do not overuse it.
|
||||
|
||||
|
||||
|
||||
## Triage rules
|
||||
|
||||
Guidance for triaging issues by WinForms team members:
|
||||
|
||||
1. Issue has no **Assignee**, unless someone is working on the issue at the moment.
|
||||
1. Use **up-for-grabs** as much as possible, ideally with a quick note about next steps / complexity of the issue.
|
||||
1. Set milestone to **Future**, unless you can 95%-commit you can fund the issue in specific milestone.
|
||||
1. Each issue has exactly one "*issue type*" label (**bug**, **enhancement**, **api-suggestion**, **test-bug**, **test-enhancement**, **question**, **documentation**, etc.).
|
||||
1. Don't be afraid to say no, or close issues - just explain why and be polite.
|
||||
1. Don't be afraid to be wrong - just be flexible when new information appears.
|
||||
|
||||
Feel free to use other labels if it helps your triage efforts (e.g. **needs-more-info**, **design-discussion**, **tenet-compatibility**, etc.).
|
||||
|
||||
### Motivation for triage rules
|
||||
|
||||
1. Issue has no **Assignee**, unless someone is working on the issue at the moment.
|
||||
* Motivation: Observation is that contributors are less likely to grab assigned issues, no matter what the repo rules say.
|
||||
1. Use **up-for-grabs** as much as possible, ideally with a quick note about next steps / complexity of the issue.
|
||||
* Note: Per http://up-for-grabs.net, such issues should be no longer than few nights' worth of work. They should be actionable (i.e. no mysterious CI failures that can't be tested in the open).
|
||||
1. Set milestone to **Future**, unless you can 95%-commit you can fund the issue in specific milestone.
|
||||
* Motivation: Helps communicate desire/timeline to community. Can spark further priority/impact discussion.
|
||||
1. Each issue has exactly one "*issue type*" label (**bug**, **enhancement**, **api-suggestion**, **test-bug**, **test-enhancement**, **question**, **documentation**, etc.).
|
||||
* Don't be afraid to be wrong when deciding 'bug' vs. 'test-bug' (flip a coin if you must). The most useful values for tracking are 'api-*' vs. 'enhancement', 'question', and 'documentation'.
|
||||
1. Don't be afraid to say no, or close issues - just explain why and be polite.
|
||||
1. Don't be afraid to be wrong - just be flexible when new information appears.
|
||||
|
||||
### PR guidance
|
||||
|
||||
1. Dont't set any labels on PRs. They are superfluous and not needed (exceptions: **NO MERGE**).
|
||||
* Motivation: All the important info (*issue type* label, API approval label, etc.) is already captured on the associated issue.
|
||||
1. Push PRs forward, don't let them go stale (response every 5+ days, ideally no PRs older than 2 weeks).
|
||||
1. Close stuck or long-term blocked PRs (e.g. due to missing API approval, etc.) and reopen them once they are unstuck.
|
||||
* Motivation: Keep only active PRs. WIP (work-in-progress) PRs should be rare and should not become stale (2+ weeks old). If a PR is stale and there is not immediate path forward, consider closing the PR until it is unblocked/unstuck.
|
||||
1. Link PR to related issue via [auto-closing](https://help.github.com/articles/closing-issues-via-commit-messages/) (add "Fixes #12345" into your PR description).
|
||||
75
README.md
75
README.md
|
|
@ -22,6 +22,8 @@ Core repos with existing code have been brought up, such as
|
|||
Even though .NET Core is a cross-platform technology, WinForms only runs on
|
||||
Windows.
|
||||
|
||||
|
||||
|
||||
## What are the benefits of building WinForms apps with .NET Core?
|
||||
|
||||
There are three primary reasons for considering .NET Core over the .NET
|
||||
|
|
@ -43,64 +45,73 @@ Framework for building desktop apps with WinForms:
|
|||
|
||||
To learn more, read the blog post [Update on .NET Core 3.0 and .NET Framework 4.8][update-post].
|
||||
|
||||
## Installation
|
||||
|
||||
Install [.NET Core 3.0 SDK Preview 1](https://www.microsoft.com/net/download).
|
||||
|
||||
[Daily builds](https://aka.ms/netcore3sdk) are also available in the
|
||||
[dotnet/code-sdk repo](https://github.com/dotnet/core-sdk).
|
||||
## Quick Links
|
||||
|
||||
To use the **WinForms designer**, you'll need Visual Studio. We recommend Visual Studio 2019 Preview 1 which is available at [https://visualstudio.microsoft.com/downloads/](https://visualstudio.microsoft.com/downloads/).
|
||||
Select the **.NET desktop development** workload with the options: **.NET Framework 4.7.2 development tools** and **.NET Core 3.0 development tools**.
|
||||
* [.NET Core 3.0 SDK Preview 1](https://www.microsoft.com/net/download)
|
||||
* [Overall .NET Core roadmap & shipdates](https://github.com/dotnet/core/blob/master/roadmap.md)
|
||||
|
||||
## Creating new applications
|
||||
|
||||
You can create a new WinForms application with `dotnet new` command, using the
|
||||
new templates for WinForms.
|
||||
|
||||
In your favorite console run:
|
||||
```cmd
|
||||
dotnet new winforms -o MyWinFormsApp
|
||||
cd MyWinFormsApp
|
||||
dotnet run
|
||||
```
|
||||
## Getting started with WinForms on .NET Core
|
||||
|
||||
## Porting existing applications
|
||||
Follow [getting started instructions](Documentation/getting-started.md).
|
||||
|
||||
To port your existing WinForms application from .NET Framework to .NET Core 3.0, refer to our [porting guidelines](https://github.com/dotnet/winforms/blob/master/porting-guidelines.md).
|
||||
|
||||
## Contributing
|
||||
|
||||
Since we're currently still porting parts of the code to GitHub, we're not
|
||||
## How to Engage, Contribute and Provide Feedback
|
||||
|
||||
Some of the best ways to contribute are to try things out, file bugs, join in design conversations, and fix issues.
|
||||
|
||||
* Use [daily builds](Documentation/getting-started.md#installation).
|
||||
* If you have a question or found a bug, [file a new issue](https://github.com/dotnet/winforms/issues/new).
|
||||
* Issues with WinForms on .NET Framework should be filed on [VS developer community](https://developercommunity.visualstudio.com/spaces/61/index.html), or [Product Support](https://support.microsoft.com/en-us/contactus?ws=support) if you have a contract.
|
||||
|
||||
**IMPORTANT:** WinForms for .NET Core 3.0 release focuses on parity with WinForms for .NET Framework.
|
||||
We do not plan to take contributions or address bugs that are not unique to WinForms on .NET Core in 3.0 release.
|
||||
Bugs which are present on both WinForms platforms (for .NET Core and .NET Framework) will be prioritized for future releases of .NET Core (post-3.0).
|
||||
|
||||
### Issue Guide
|
||||
|
||||
Read our detailed [issue guide](Documentation/issue-guide.md) which covers:
|
||||
|
||||
* How to file high-quality bug reports
|
||||
* How to use and understand Labels, Milestones, Assignees and Upvotes on issues
|
||||
* How to escalate (accidentally) neglected issue or PR
|
||||
* How we triage issues
|
||||
|
||||
For general .NET Core 3 issues (not specific to WinForms), use the [.NET Core repo](https://github.com/dotnet/core/issues) or other repos if appropriate (e.g. [CoreFX](https://github.com/dotnet/corefx/issues), [WPF](https://github.com/dotnet/wpf/issues)).
|
||||
|
||||
### Contributing Guide
|
||||
|
||||
Since we're currently still porting parts of WinForms codebase to GitHub, we're not
|
||||
equipped to handle larger contributions yet. Our goal is to accept contributions
|
||||
on day one, but we'll only be able to accept minor modifications (typos, build
|
||||
fixes, test breaks etc). We'll be happy to hear your feedback!
|
||||
|
||||
* For WinForms on .NET Core, you can simply file bugs and feature requests in
|
||||
[this repo](https://github.com/dotnet/winforms/issues/new).
|
||||
* For WinForms on .NET Framework, please us the existing [Visual Studio
|
||||
developer community](https://developercommunity.visualstudio.com/spaces/61/index.html).
|
||||
* For .NET Core 3 in general, use the [.NET Core](https://github.com/dotnet/core/issues/) repo.
|
||||
For more details, take a look at the [.NET Core Contribution Guidelines](https://github.com/dotnet/coreclr/blob/master/Documentation/project-docs/contributing.md).
|
||||
|
||||
For more details, take a look at the [.NET Core Contribution
|
||||
Guidelines](https://github.com/dotnet/coreclr/blob/master/Documentation/project-docs/contributing.md).
|
||||
|
||||
## Community
|
||||
### Community
|
||||
|
||||
This project has adopted the code of conduct defined by the [Contributor Covenant](https://contributor-covenant.org/)
|
||||
to clarify expected behavior in our community.
|
||||
For more information, see the [.NET Foundation Code of Conduct](https://dotnetfoundation.org/code-of-conduct).
|
||||
|
||||
## Samples
|
||||
### Reporting security issues and security bugs
|
||||
|
||||
Security issues and bugs should be reported privately, via email, to the Microsoft Security Response Center (MSRC) <secure@microsoft.com>. You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Further information, including the MSRC PGP key, can be found in the [Security TechCenter](https://www.microsoft.com/msrc/faqs-report-an-issue).
|
||||
|
||||
Also see info about related [Microsoft .NET Core and ASP.NET Core Bug Bounty Program](https://www.microsoft.com/msrc/bounty-dot-net-core).
|
||||
|
||||
|
||||
Check out the WinForms
|
||||
[samples](https://github.com/dotnet/samples/tree/master/windowsforms) for
|
||||
HelloWorld examples and more advanced scenarios.
|
||||
|
||||
## License
|
||||
|
||||
.NET Core (including WinForms repo) is licensed under the [MIT license](LICENSE.TXT).
|
||||
|
||||
|
||||
|
||||
## .NET Foundation
|
||||
|
||||
.NET Core WinForms is a [.NET Foundation](https://www.dotnetfoundation.org/projects) project.
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче