Git_Mirror/Terminal.Gui
1
0
Fork 0
mirror of https://github.com/gui-cs/Terminal.Gui.git synced 2025-12-26 15:57:56 +01:00
Code Issues Packages Projects Releases Wiki Activity
Files
6144c9da666b9cad202de62dd6e85ed4a65654f6
Terminal.Gui/CONTRIBUTING.md

5.1 KiB
Raw Blame History

Contributing to Terminal.Gui

We welcome contributions from the community. See Issues for a list of open bugs and enhancements. Contributors looking for something fun to work on should look at issues taged as:

Coding Style

Terminal.Gui follows the Mono 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 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 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 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 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 tag.

  1. Stand on the shoulders of giants. Follow the Microsoft .NET Framework 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.

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 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.

Examples & Tests

Terminal.Gui does an automated unit or regression test suite (please feel free to help build one). Until such a suite is available, the best we have is the 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.