Skip to content

Latest commit

 

History

History
42 lines (27 loc) · 3.4 KB

CONTRIBUTING.md

File metadata and controls

42 lines (27 loc) · 3.4 KB
Raw

How to contribute to the Medley Interlisp project

First, we want to thank you for helping reach the goal of restoring Medley Interlisp to the point where it is as useful today as it was 30 years ago.

This guide is meant to help you make useful contributions, whether to the Maiko C-based virtual machine implementation, the Medley Lisp code (in Interlisp and Common Lisp), or documentation. There are a number of GitHub problems that could use some attention.

Working with Maiko

Be aware that we are working with 30-year-old code, and there are quite a few unforseen interactions. The C code was originally written to K&R C before C standards, for a big-endian 32-bit machine.

Working with Medley

The current arrangement of files and extentions is awkward for working on the implementation. We're still cataloging what we have and how well it works.

  • The most useful contributions are reproducible errors -- things that don't work as documented.
  • Second most useful are reports of unexpected behavior -- things that aren't documented but behave unexpectedly.

Reporting a bug or feature request

  • Ensure the bug was not already reported by searching on GitHub under Issues or Discussions. Note that all issues and Discussions are found in the Medley repository, using labels to distinguish. Discussions are for questions or topics where there is some disagreement or uncertainty about the "right" direction.
  • If you're unable to find a discussion or open issue addressing the problem, open a new one. Be sure to include a title and clear description, as much relevant information as possible. Use the issue templates to guide you. See this guide.

Did you write a patch that fixes a bug?

  • Some bug fixes and "improvements" have unintended consequences, well beyond what you might expect for well-written modern code. We don't have testing new builds automated or integrated. Be sure you've tested your patch.
  • Open a new GitHub pull request with the patch.
  • Ensure the PR description clearly describes the problem and solution. Include the relevant issue number if applicable.
  • Keep Pull Requests small and easily reviewable. https://www.thedroidsonroids.com/blog/splitting-pull-request for a writeup of good practices.

Note that changes that are cosmetic in nature and do not add anything substantial to the stability, functionality, or testability of Medley Interlisp will generally not be accepted.

Do you intend to add a new feature or change an existing one?

  • Suggest your change as a Discussion before starting to write code. Is the feature consistent with the overall Medley Interlisp project goals?
  • Do not open an issue on GitHub until you have collected positive feedback about the change. GitHub issues are primarily intended for bug reports and fixes.

Medley Interlisp is a volunteer effort. We want to make this a fun experience for everyone. We encourage you to pitch in and join the team.

(These guidelines adapted from https://github.com/rails/rails/blob/master/CONTRIBUTING.md )