Contributing

Reporting issues

At this time, the most useful thing you can do to help is and useful bug reports to the Issue Tracker

In your report, please discuss what you wanted to happen as well as what happened. Also, please include enough information to reproduce the issue. Such as:

  • the name and version of the program you were running - usually a shell

  • the version of Emacs you’re running, taken, for example, from M-x about-emacs

  • whether you’re running Emacs in a window environment or a terminal

  • what kind of prompt you’re using, that is, what it looks like, what character it ends with, how many lines it has and whether you’re using any kind of right prompt

If you can reproduce reliably, please include the content of the buffer *mistty-log* into your report, as follows:

  • Enable logging by calling M-x mistty-start-log

  • Reproduce the issue

  • Go to the buffer *mistty-log*

  • Call M-x mistty-stop-log to avoid getting more log entries

  • Copy the buffer content and paste it into the issue. The log includes everything that you write to the terminal and everything that you get back from the terminal. Please make sure you’re not including any private information, such as password - remove them if necessary…

If you cannot reproduce reliably,

  • go to M-x customize-option mistty-backlog-size to set the backlog size to a large value, such as 50

  • use MisTTY normally, until the issue comes back

  • once it has happened again, immediately call M-x mistty-start-log. The log will then contain entries for events that happened just before you called the command.

  • call M-x mistty-stop-log

  • copy the content of the *mistty-log* buffer, strip out anything private, and include it into the issue.

Suggesting features

Please create a new discussion in the Ideas category or add a feature suggestions to the Issue Tracker.

Asking questions

Start a new discussion with your question in the General category.

Code contributions

To contribute code to the project, open a Pull Request.

Before you do that, please make sure the any new features is covered by tests and that the tests pass.

To run the tests, install and setup eldev, then run eldev test.

Tests can also be run from inside of Emacs, using M-x ert-run-tests-interactively but when you do so, be aware that there might be unexpected interaction with your Emacs configurations. The tests passing reliably when run using eldev test is what matters.

Please also make sure your commit message follows Conventional Commits 1.0.0, in short, the commit message of new features should start with “feat: “, fixes with “fix: “, refactorings with “refactor: ” and tests with “test: “.

Documentation contributions

You don’t need to be a developer to contribute! Contribution to the documentation or code comments are very welcome. Please open a Pull Request with your proposed modifications. To follow Conventional Commits 1.0.0, the commit message should start with “docs: “

The documentation is written in reStructuredText. You’ll need to install Sphinx to build it:

python3 -m venv venv
. venv/bin/activate # or activate.fish on fish
pip3 install -r docs/requirements.txt

Then run eldev html to build the documentation.