95e015329d
Update project contributor guidelines Replace the documentation link to point to the Documentation section of the project site instead of the discontinued Wiki. Under Working with Medley, advise opening an issue to report errors and unexpected behaviors. Under Did you write a patch that fixes a bug?, remove the link to Maiko PRs as the project has more repos a contributor may want to open PRs for. Signed-off-by: Paolo Amoroso <paolo.amoroso@gmail.com>
45 lines
3.5 KiB
Markdown
45 lines
3.5 KiB
Markdown
# How to contribute to the [Medley Interlisp project](https://Interlisp.org)
|
|
|
|
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](https://github.com/Interlisp/maiko) C-based virtual machine implementation, the [Medley](https://github.com/Interlisp/medley) Lisp code (in Interlisp and Common Lisp), or [documentation](https://interlisp.org/software/using-medley). There are a number of [GitHub](https://github.com/Interlisp/medley/discussions/categories/github-use) 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.
|
|
|
|
To report these errors and behaviors [open an issue](https://github.com/Interlisp/medley/issues).
|
|
|
|
## Reporting a bug or feature request
|
|
* Ensure the bug was not already reported by searching on GitHub under [Issues](https://github.com/Interlisp/medley/issues) or [Discussions](https://github.com/Interlisp/medley/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](https://github.com/ncovercash/reporting-bugs-effectively/blob/master/ENGLISH.md).
|
|
|
|
## 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 )
|