-
Notifications
You must be signed in to change notification settings - Fork 696
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
added contribution guidelines, project layout docs, etc...
- Loading branch information
Showing
4 changed files
with
158 additions
and
5 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,76 @@ | ||
| # Contributor Covenant Code of Conduct | ||
|
|
||
| ## Our Pledge | ||
|
|
||
| In the interest of fostering an open and welcoming environment, we as | ||
| contributors and maintainers pledge to making participation in our project and | ||
| our community a harassment-free experience for everyone, regardless of age, body | ||
| size, disability, ethnicity, sex characteristics, gender identity and expression, | ||
| level of experience, education, socio-economic status, nationality, personal | ||
| appearance, race, religion, or sexual identity and orientation. | ||
|
|
||
| ## Our Standards | ||
|
|
||
| Examples of behavior that contributes to creating a positive environment | ||
| include: | ||
|
|
||
| * Using welcoming and inclusive language | ||
| * Being respectful of differing viewpoints and experiences | ||
| * Gracefully accepting constructive criticism | ||
| * Focusing on what is best for the community | ||
| * Showing empathy towards other community members | ||
|
|
||
| Examples of unacceptable behavior by participants include: | ||
|
|
||
| * The use of sexualized language or imagery and unwelcome sexual attention or | ||
| advances | ||
| * Trolling, insulting/derogatory comments, and personal or political attacks | ||
| * Public or private harassment | ||
| * Publishing others' private information, such as a physical or electronic | ||
| address, without explicit permission | ||
| * Other conduct which could reasonably be considered inappropriate in a | ||
| professional setting | ||
|
|
||
| ## Our Responsibilities | ||
|
|
||
| Project maintainers are responsible for clarifying the standards of acceptable | ||
| behavior and are expected to take appropriate and fair corrective action in | ||
| response to any instances of unacceptable behavior. | ||
|
|
||
| Project maintainers have the right and responsibility to remove, edit, or | ||
| reject comments, commits, code, wiki edits, issues, and other contributions | ||
| that are not aligned to this Code of Conduct, or to ban temporarily or | ||
| permanently any contributor for other behaviors that they deem inappropriate, | ||
| threatening, offensive, or harmful. | ||
|
|
||
| ## Scope | ||
|
|
||
| This Code of Conduct applies both within project spaces and in public spaces | ||
| when an individual is representing the project or its community. Examples of | ||
| representing a project or community include using an official project e-mail | ||
| address, posting via an official social media account, or acting as an appointed | ||
| representative at an online or offline event. Representation of a project may be | ||
| further defined and clarified by project maintainers. | ||
|
|
||
| ## Enforcement | ||
|
|
||
| Instances of abusive, harassing, or otherwise unacceptable behavior may be | ||
| reported by contacting the project team at [email protected]. All | ||
| complaints will be reviewed and investigated and will result in a response that | ||
| is deemed necessary and appropriate to the circumstances. The project team is | ||
| obligated to maintain confidentiality with regard to the reporter of an incident. | ||
| Further details of specific enforcement policies may be posted separately. | ||
|
|
||
| Project maintainers who do not follow or enforce the Code of Conduct in good | ||
| faith may face temporary or permanent repercussions as determined by other | ||
| members of the project's leadership. | ||
|
|
||
| ## Attribution | ||
|
|
||
| This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, | ||
| available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html | ||
|
|
||
| [homepage]: https://www.contributor-covenant.org | ||
|
|
||
| For answers to common questions about this code of conduct, see | ||
| https://www.contributor-covenant.org/faq |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,44 @@ | ||
| # 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 taged 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) | ||
|
|
||
| ## 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. | ||
|
|
||
| ## 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 guideliens submit an Issue using the [design](https://github.com/migueldeicaza/gui.cs/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. | ||
| 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. | ||
|
|
||
| ## Public API Tenets & Guidelines | ||
|
|
||
| **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 backwards compatabiltiy. | ||
|
|
||
| *NOTE: Like all tenets, these are up for debate. If you disagree, have questions, or suggestions about these tenets and guideliens submit an Issue using the [design](https://github.com/migueldeicaza/gui.cs/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 parallel 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 counter example is [Issue #447](https://github.com/migueldeicaza/gui.cs/issues/447). | ||
|
|
||
| ## 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. | ||
| - 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). | ||
|
|
||
| ## Examples & Tests | ||
|
|
||
| **Terminal.Gui** does an automated unit or regression test suite ([please feel free to help build one](https://github.com/migueldeicaza/gui.cs/issues/566)). Until such a suite is available, the best we have is the [UICatalog](https://github.com/migueldeicaza/gui.cs/tree/master/UICatalog) sample app. | ||
|
|
||
| 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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,25 @@ | ||
| # Terminal.Gui Project | ||
|
|
||
| Contains all files required to build the **Terminal.Gui** library (and nuget package). | ||
|
|
||
| ## Project Folder Structure | ||
|
|
||
| - `Terminal.Gui.sln` - The Visual Studio 2019 solution | ||
| - `Core/` - Source files for all types that comprise the core building blocks of **Terminal-Gui** | ||
| - `Application` - A `static` class that provides the base 'application driver'. Given it defines a **Terminal.Gui** application it is both logically and literally (because `static`) a singleton. It has direct dependencies on `MainLoop`, `Events.cs` `NetDriver`, `CursesDriver`, `WindowsDriver`, `Responder`, `View`, and `TopLevel` (and nothing else). | ||
| - `MainLoop` - Defines `IMainLoopDriver` and implements the and `MainLoop` class. | ||
| - `ConsoleDriver` - Definition for the Console Driver API. | ||
| - `Events.cs` - Defines keyboard and mouse related structs & classes. | ||
| - `PosDim.cs` - Implements **Terminal-Gui's** *Computed Layout* system. These classes have deep dependencies on `View`. | ||
| - `Responder` - Base class for the windowing class heirachy. Implements support for keyboard & mouse input. | ||
| - `View` - Derived from `Responder`, the base class for non-modal visual elements such as controls. | ||
| - `Toplevel` - Drived from `View`, the base class for modal visual elements such as top-level windows and dialogs. Supports the concept of `MenuBar` and `StatusBar`. | ||
| - `Window` - Drived from `TopLevel`, implements Toplevel views with a visible frame and Title. | ||
| - `Types/` - A folder (not namespace) containing implementations of `Point`, `Rect`, and `Size` which are ancient versions of the modern `System.Drawing.Point`, `System.Drawing.Size`, and `System.Drawning.Rectangle`. | ||
| - `ConsoleDrivers/` - Source files for the three `ConsoleDriver`-based drivers: .NET: `NetDriver`, Unix & Mac: `UnixDriver`, and Windows: `WindowsDriver`. | ||
| - `Views/` - A folder (not namespace) containing the source for all built-in classes that drive from `View` (non-modals). | ||
| - `Windows/` - A folder (not namespace) containing the source all built-in classes that derive from `Window`. | ||
|
|
||
| ## Contributing | ||
|
|
||
| See [CONTRIBUTING.md](https://github.com/migueldeicaza/gui.cs/blob/master/CONTRIBUTING.md). |