mirror of
https://github.com/gui-cs/Terminal.Gui.git
synced 2025-12-26 15:57:56 +01:00
Merge branch 'develop' of tig:gui-cs/Terminal.Gui into develop
This commit is contained in:
Tig Kindel
52
.github/CODEOWNERS
vendored
Normal file
52
.github/CODEOWNERS
vendored
Normal file
@@ -0,0 +1,52 @@
|
||||
# These owners will be the default owners for everything in
|
||||
# the repo. Unless a later match takes precedence,
|
||||
# @global-owner1 and @global-owner2 will be requested for
|
||||
# review when someone opens a pull request.
|
||||
* @migueldeicaza @tig
|
||||
|
||||
# Order is important; the last matching pattern takes the most
|
||||
# precedence. When someone opens a pull request that only
|
||||
# modifies JS files, only @js-owner and not the global
|
||||
# owner(s) will be requested for a review.
|
||||
#*.js @js-owner
|
||||
|
||||
# You can also use email addresses if you prefer. They'll be
|
||||
# used to look up users just like we do for commit author
|
||||
# emails.
|
||||
#*.go docs@example.com
|
||||
|
||||
# Teams can be specified as code owners as well. Teams should
|
||||
# be identified in the format @org/team-name. Teams must have
|
||||
# explicit write access to the repository. In this example,
|
||||
# the octocats team in the octo-org organization owns all .txt files.
|
||||
#*.txt @octo-org/octocats
|
||||
|
||||
# In this example, @doctocat owns any files in the build/logs
|
||||
# directory at the root of the repository and any of its
|
||||
# subdirectories.
|
||||
#/build/logs/ @doctocat
|
||||
|
||||
# The `docs/*` pattern will match files like
|
||||
# `docs/getting-started.md` but not further nested files like
|
||||
# `docs/build-app/troubleshooting.md`.
|
||||
#docs/* docs@example.com
|
||||
|
||||
# In this example, @octocat owns any file in an apps directory
|
||||
# anywhere in your repository.
|
||||
#apps/ @octocat
|
||||
|
||||
# In this example, @doctocat owns any file in the `/docs`
|
||||
# directory in the root of your repository and any of its
|
||||
# subdirectories.
|
||||
#/docs/ @doctocat
|
||||
|
||||
# In this example, any change inside the `/scripts` directory
|
||||
# will require approval from @doctocat or @octocat.
|
||||
#/scripts/ @doctocat @octocat
|
||||
|
||||
# In this example, @octocat owns any file in the `/apps`
|
||||
# directory in the root of your repository except for the `/apps/github`
|
||||
# subdirectory, as its owners are left empty.
|
||||
#/apps/ @octocat
|
||||
#/apps/github
|
||||
|
||||
@@ -1,23 +1,76 @@
|
||||
# Contributing to Terminal.Gui
|
||||
|
||||
We welcome contributions from the community. See [Issues](https://github.com/migueldeicaza/gui.cs/issues) for a list of open [bugs](https://github.com/migueldeicaza/gui.cs/issues?q=is%3Aopen+is%3Aissue+label%3Abug) and [enhancements](https://github.com/migueldeicaza/gui.cs/issues?q=is%3Aopen+is%3Aissue+label%3Aenhancement). Contributors looking for something fun to work on should look at issues tagged as:
|
||||
We welcome contributions from the community. See [Issues](https://github.com/gui-cs/Terminal.Gui/issues) for a list of open [bugs](https://github.com/gui-cs/Terminal.Gui/issues?q=is%3Aopen+is%3Aissue+label%3Abug) and [enhancements](https://github.com/gui-cs/Terminal.Gui/issues?q=is%3Aopen+is%3Aissue+label%3Aenhancement). Contributors looking for something fun to work on should look at issues tagged as:
|
||||
|
||||
- [good first issue](https://github.com/migueldeicaza/gui.cs/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)
|
||||
- [up for grabs](https://github.com/migueldeicaza/gui.cs/issues?q=is%3Aopen+is%3Aissue+label%3Aup-for-grabs)
|
||||
- [help wanted](https://github.com/migueldeicaza/gui.cs/issues?q=is%3Aopen+is%3Aissue+label%3Aup-for-grabs)
|
||||
- [good first issue](https://github.com/gui-cs/Terminal.Gui/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)
|
||||
- [up for grabs](https://github.com/gui-cs/Terminal.Gui/issues?q=is%3Aopen+is%3Aissue+label%3Aup-for-grabs)
|
||||
- [help wanted](https://github.com/gui-cs/Terminal.Gui/issues?q=is%3Aopen+is%3Aissue+label%3Aup-for-grabs)
|
||||
|
||||
## Forking and Submitting Changes
|
||||
|
||||
Terminal.Gui uses the [GitFlow](https://nvie.com/posts/a-successful-git-branching-model/) branching model.
|
||||
|
||||
* The `main` branch is always stable, and always matches the most recently released Nuget package.
|
||||
* The `develop` branch is where new development and bug-fixes happen. It is the default branch.
|
||||
|
||||
### Forking Terminal.Gui
|
||||
* Use GitHub to fork the `Terminal.Gui` repo to your account (https://github.com/gui-cs/Terminal.Gui/fork).
|
||||
* Clone your fork to your local machine (`git clone https://github.com/<yourID>/Terminal.Gui`)
|
||||
* This will be your `origin` remote
|
||||
* Add a remote for `upstream`: `git remote add upstream https://github.com/gui-cs/Terminal.Gui`
|
||||
|
||||
### Making Changes and Submitting Pull Requests
|
||||
|
||||
#### When you start to make a change
|
||||
|
||||
Ensure your local `develop` branch is up-to-date with `upstream` (`github.com/gui-cs/Terminal.Gui`):
|
||||
```powershell
|
||||
cd ./Terminal.Gui
|
||||
git checkout develop
|
||||
git pull upstream develop
|
||||
```
|
||||
|
||||
Create a new local branch:
|
||||
```powershell
|
||||
git checkout -b "my_new_branch"
|
||||
```
|
||||
|
||||
#### Making Changes
|
||||
Follow all the guidelines below.
|
||||
|
||||
* Coding Style
|
||||
* Unit Tests
|
||||
* Sample Code
|
||||
* API Documentation
|
||||
* etc...
|
||||
|
||||
When you're ready, commit your changes:
|
||||
|
||||
```powershell
|
||||
git add .
|
||||
git commit -m "Fixes #1234. Some bug"
|
||||
```
|
||||
|
||||
### Submitting a Pull Request
|
||||
|
||||
Push your local branch to your fork (`origin`):
|
||||
|
||||
```powershell
|
||||
git push
|
||||
```
|
||||
|
||||
## Coding Style
|
||||
|
||||
**Terminal.Gui** follows the [Mono Coding Guidelines](https://www.mono-project.com/community/contributing/coding-guidelines/). `../.editorconfig` uses Visual Studio to help enforce these.
|
||||
**Terminal.Gui** follows the [Mono Coding Guidelines](https://www.mono-project.com/community/contributing/coding-guidelines/). [`/.editorconfig`](https://github.com/gui-cs/Terminal.Gui/blob/b0a43ba338adf5ec069066e5a7dff8fea39b41db/.editorconfig) enforces this style in Visual Studio. Use `Ctrl-K-D` in Visual Studio to have it reformat code.
|
||||
|
||||
## User Experience Tenets
|
||||
|
||||
**Terminal.Gui**, as a UI framework, heavily influences how console graphical user interfaces (GUIs) work. We use the following [tenets](https://ceklog.kindel.com/2020/02/10/tenets/) to guide us:
|
||||
|
||||
*NOTE: Like all tenets, these are up for debate. If you disagree, have questions, or suggestions about these tenets and guidelines submit an Issue using the [design](https://github.com/migueldeicaza/gui.cs/issues?q=is%3Aopen+is%3Aissue+label%3Adesign) tag.*
|
||||
*NOTE: Like all tenets, these are up for debate. If you disagree, have questions, or suggestions about these tenets and guidelines submit an Issue using the [design](https://github.com/gui-cs/Terminal.Gui/issues?q=is%3Aopen+is%3Aissue+label%3Adesign) tag.*
|
||||
|
||||
1. **Honor What's Come Before**. The Mac and Windows OS's have well-established GUI idioms that are mostly consistent. We adhere to these versus inventing new ways for users to do things. For example, **Terminal.Gui** adopts the `ctrl/command-c`, `ctrl/command-v`, and `ctrl/command-x` keyboard shortcuts for cut, copy, and paste versus defining new shortcuts.
|
||||
2. **Consistency Matters**. Common UI idioms should be consistent across the GUI framework. For example, `ctrl/command-q` quits/exits all modal views. See [Issue #456](https://github.com/migueldeicaza/gui.cs/issues/456) as a counter-example that should be fixed.
|
||||
2. **Consistency Matters**. Common UI idioms should be consistent across the GUI framework. For example, `ctrl/command-q` quits/exits all modal views. See [Issue #456](https://github.com/gui-cs/Terminal.Gui/issues/456) as a counter-example that should be fixed.
|
||||
3. **Honor the OS, but Work Everywhere**. **Terminal.Gui** is cross-platform, but we support taking advantage of a platform's unique advantages. For example, the Windows Console API is richer than the Unix API in terms of keyboard handling. Thus, in Windows pressing the `alt` key in a **Terminal.Gui** app will activate the `MenuBar`, but in Unix, the user has to press the full hotkey (e.g. `alt-f`) or `F9`.
|
||||
4. **Keyboard first, Mouse also**. Users use consoles primarily with the keyboard; **Terminal.Gui** is optimized for getting stuff done without using the Mouse. However, as a GUI framework, the Mouse is essential thus we strive to ensure that everything also works via the Mouse.
|
||||
|
||||
@@ -25,12 +78,12 @@ We welcome contributions from the community. See [Issues](https://github.com/mig
|
||||
|
||||
**Terminal.Gui** provides an API that is used by many. As the project evolves, contributors should follow these [tenets](https://ceklog.kindel.com/2020/02/10/tenets/) to ensure Consistency and backward compatibility.
|
||||
|
||||
*NOTE: Like all tenets, these are up for debate. If you disagree, have questions, or suggestions about these tenets and guidelines submit an Issue using the [design](https://github.com/migueldeicaza/gui.cs/issues?q=is%3Aopen+is%3Aissue+label%3Adesign) tag.*
|
||||
*NOTE: Like all tenets, these are up for debate. If you disagree, have questions, or suggestions about these tenets and guidelines submit an Issue using the [design](https://github.com/gui-cs/Terminal.Gui/issues?q=is%3Aopen+is%3Aissue+label%3Adesign) tag.*
|
||||
|
||||
1. **Stand on the shoulders of giants.** Follow the [Microsoft .NET Framework Design Guidelines](https://docs.microsoft.com/en-us/dotnet/standard/design-guidelines/) where appropriate.
|
||||
2. **Don't Break Existing Stuff.** Avoid breaking changes to user behavior or the public API; instead, figure out how to implement new functionality in a similar way. If a breaking change can't be avoided, follow the guidelines below.
|
||||
3. **Fail-fast.** Fail-fast makes bugs and failures appear sooner, leading to a higher-quality framework and API.
|
||||
4. **Standards Reduce Complexity**. We strive to adopt standard API idoms because doing so reduces complexity for users of the API. For example, see Tenet #1 above. A counterexample is [Issue #447](https://github.com/migueldeicaza/gui.cs/issues/447).
|
||||
4. **Standards Reduce Complexity**. We strive to adopt standard API idoms because doing so reduces complexity for users of the API. For example, see Tenet #1 above. A counterexample is [Issue #447](https://github.com/gui-cs/Terminal.Gui/issues/447).
|
||||
|
||||
### Include API Documentation
|
||||
|
||||
@@ -82,14 +135,14 @@ See also: https://www.codeproject.com/Articles/20550/C-Event-Implementation-Fund
|
||||
|
||||
## Breaking Changes to User Behavior or the Public API
|
||||
|
||||
- Tag all pull requests that cause breaking changes to user behavior or the public API with the [breaking-change](https://github.com/migueldeicaza/gui.cs/issues?q=is%3Aopen+is%3Aissue+label%3Abreaking-change) tag. This will help project maintainers track and document these.
|
||||
- Tag all pull requests that cause breaking changes to user behavior or the public API with the [breaking-change](https://github.com/gui-cs/Terminal.Gui/issues?q=is%3Aopen+is%3Aissue+label%3Abreaking-change) tag. This will help project maintainers track and document these.
|
||||
- Add a `<remark></remark>` to the XML Documentation to the code describing the breaking change. These will get picked up in the [API Documentation](https://migueldeicaza.github.io/gui.cs/api/Terminal.Gui/Terminal.Gui.html).
|
||||
|
||||
## Unit Tests
|
||||
|
||||
PRs should never cause code coverage to go down. Ideally, every PR will get the project closer to 100%. PRs that include new functionality (e.g. a new control) should have at least 70% code coverage for the new functionality.
|
||||
|
||||
**Terminal.Gui** has an automated unit or regression test suite. See the [Testing wiki](https://github.com/migueldeicaza/gui.cs/wiki/Testing).
|
||||
**Terminal.Gui** has an automated unit or regression test suite. See the [Testing wiki](https://github.com/gui-cs/Terminal.Gui/wiki/Testing).
|
||||
|
||||
We analyze unit tests and code coverage on each PR push.
|
||||
|
||||
@@ -116,6 +169,6 @@ Then open up the resulting `coverage.opencover.xml` file and you'll see the `seq
|
||||
|
||||
## Sample Code
|
||||
|
||||
[UI Catalog](https://github.com/migueldeicaza/gui.cs/tree/master/UICatalog) is a great sample app for manual testing.
|
||||
[UI Catalog](https://github.com/gui-cs/Terminal.Gui/tree/master/UICatalog) is a great sample app for manual testing.
|
||||
|
||||
When adding new functionality, fixing bugs, or changing things, please either add a new `Scenario` to **UICatalog** or update an existing `Scenario` to fully illustrate your work and provide a test-case.
|
||||
|
||||
19
pull_request_template.md
Normal file
19
pull_request_template.md
Normal file
@@ -0,0 +1,19 @@
|
||||
## Description
|
||||
|
||||
Please include a terse summary of the change or which issue is fixed.
|
||||
|
||||
If an Issue was fixed, write "Fixes #issuenumber" as this will help Github automatically close that issue once the PR is merged.
|
||||
|
||||
## Temrminal.Gui Pull Request checklist:
|
||||
|
||||
- [ ] My code follows the [style guidelines of Terminal.Gui](https://github.com/gui-cs/Terminal.Gui/blob/develop/.editorconfig) - if you use Visual Studio, hit `CTRL-K-D` to automatically reformat your files before committing.
|
||||
- [ ] Mhy code follows the [Terminal.Gui library design guidelines](https://github.com/gui-cs/Terminal.Gui/blob/develop/CONTRIBUTING.md)
|
||||
- [ ] I ran `dotnet test` before commit
|
||||
- [ ] I have performed a self-review of my own code
|
||||
- [ ] I have commented my code, particularly in hard-to-understand areas
|
||||
- [ ] I have made corresponding changes to the API documentation (using `///` style comments)
|
||||
- [ ] My changes generate no new warnings
|
||||
- [ ] I have checked my code and corrected any poor grammar or misspellings
|
||||
- [ ] My pull request generate no conflicts with `develop` branch
|
||||
- [ ] I tested my code on at least Windows and Linux
|
||||
- [ ] I conducted basic QA to assure all features are working
|
||||
Reference in New Issue
Block a user