Contributing to Plasma

Paul Bone
<paul@plasmalang.org>
version 0.1, October, 2019
Table of Contents

This file contains information for potential and current Plasma contributors.

  • We prefer github pull requests or patches mailed to the developers' mailing list. If you need to discuss a security issue confidently you can e-mail plasma at plasmalang dot org

  • The license of your contribution must match the project’s licenses:

    • Code: MIT

    • Docs: CC BY-SA 4.0

    • Build scripts, tests, and sample code: Unlicense

  • No contributor agreement is required, you retain the copyright for your contribution.

  • Add your name to the AUTHORS file.

  • Please follow the style guides as much as possible (see below)

  • Please format your log messages following the log message style (see below)

  • By opening a PR you acknowledge these terms and agree to the Code of Conduct.

  • By opening an issue or adding a comment or message you also agree to the Code of Conduct.

Getting started

For information on how to setup the dependencies and compile Plasma the best place to start is the Getting Started Guide. This is part of our set of developer documentation whicn includes specific guides and general documents such as style guides.

vim

If you’ll be working on the compiler you probably want some editor support for Mercury. Support is included in the Mercury repository/source distribution if you’ve used the Debian package it’s at /usr/share/doc/mercury-rotd-tools/examples/vim/

You may also wish to use the extra script and configuration change to make it easier to build the Mercury sources from within vim.

What to contribute

You want to contribute but aren’t sure what you’d like to work on?

The most valuable contributions will fit with Plasma’s goals and current development status (project roadmap). The project is at an early stage and therefore we are prioritising work that makes the language useful above things like compiler optimisations.

Suggestions and good first bugs

If you’re looking for a suggestion of what to contribute please consider the open unassigned github issues

We label our issues within github to help searchability but also to provide some ideas about what is involved with each issue. Some issues have the good-first-bug label. These tend to be really small changes that require relatively little experience to complete. They should take someone with a year of programming experience no more than 2 hours, usually much less. They might not be suitable for someone in their first month or two of programming. The no-domain-knowledge label contains more difficult changes. These may require a fair amount of programming experience but they do not require any programming language implementation experience, or otherwise have very clear help.

Other labels can indicate what component they are relevant to, for example: component: docs or component: compiler. Or what skills may be required skill: C++. There is also a help wanted label for anything where people already involved with the project might not have the skills we think are required.

If you file a new bug, do not worry about adding labels, a project maintainer will follow this guide to triage it.

There are also many TODO and XXX notes in the source code, which things that are not handled. Search for the strings TODO and XXX. Keep in mind that there may be good reasons why these are not yet handled, eg: it may depend on other incomplete work.

If you find something undocumented whose behaviour is unlikely to change, consider filling in that part of the documentation.

When reading code if something isn’t clear, please ask us about it. We’ll also take this as a hint that we should have written (better) code comments or docs.

Get in contact

If you’ve got a big idea it’s often good to discuss it with us before starting. We may be able to give you some pointers or let you know what kinds of problems you may encounter. For example we might not be interested n making the language weakly typed and discussing this beforehand may avoid disappointment later. Ultimately we want you to enjoy working with Plasma and that means making the most of your development time.

How to contribute

We want to build a great language and we also want you/us to have a good time building a great language. These guidelines will make it easier for us to review and maintain your code, and hopefully for you to have a better experience during code-review.

Before beginning

It is best to start each piece of work on a new git branch. Create a branch off of master and commit your changes there as you go.

Open/comment on/assign yourself on an issue. Let us know what you want to work as part of github’s issue tracking (see above). We can add you to the Plasma project so that you can be assigned to an issue, then we know who is working on it.

Making your changes

If you’re making a series of patches, try to organise the patches so that each patch makes sense on its own. Git has many features for doing this including cherry picking and rebasing.

Code contributions should follow the style guides as much as possible. Deviations that make code more readable are permitted. The guides are Mercury style guide and C style guide.

TODO: Provide information about project structure.

Spell check and test your work, use make test for the latter. Each patch should, when applied in series, pass the test suite.

Documenting your changes

User-visible changes including new options, features and behaviours should be documented. For now options are documented in the --help text of each program. While designs and concepts are documented in one of the files in the docs directory, these files are asciidoc text files.

Submitting your changes

All code contributions must be made under the appropriate license:

  • Code: MIT

  • Docs: CC BY-SA 4.0

  • Build scripts, tests, and sample code: Unlicense

No transfer of copyright or other rights or permissions is required. All contributors should be listed in the AUTHORS file, and all contributors with copyrights must be listed (pseudonyms are okay, we just need to track who owns Plasma to protect Plasma).

Log messages should follow the style:

[component(s)] Title
Description
Any other changes including changes that were needed to support this
change or followed as a concequence of this change.

We provide a .gitmessage in the root of the repository. Run this command to start using the new commit message template:

git config --local commit.template /path/to/repo/.gitmessage

components is one or more parts of the system. This helps people identify (in mailing lists, change logs etc) what kind of change has been made at a glace. It also helps people and software search for changes. Current components are:

  • pz: the PZ file format,

  • rt: the runtime generally,

  • rt/interp: the bytecode interpreter,

  • rt/gc: the garbage collector,

  • asm: the PZ assembler,

  • compiler: the compiler generally,

  • compiler/parse: the first phase: parsing.

  • compiler/ast: the second phase: the AST and operations on it,

  • compiler/pre: the third phase: the pre-core representation and operations,

  • compiler/core: the fourth phase: the core representation and operations,

  • compiler/pz: the fitht phase: the PZ code generator,

  • docs: documentation,

  • build: the build system,

  • tests: the test suite,

Sometimes it makes sense to pick the component with the most significant changes rather than listing all of them. This is typical for changes to the compiler.

Each patch should contain a single change and changes required by that change (should compile and pass tests). Changes may be rolled together when they’re trivial related changes (eg, multiple spelling fixes).

We accept contributions via pull request on github, or via e-mailed patches. If you choose to use e-mailed patches then the git format-patchi and/or git send-email tools can generate nice e-mails, however this is not required, diff -uNr is sufficient. E-mailed patches should be sent to the dev mailing list.

TODO: Provide suitable step-by-step instructions.

Our review policy

We aim to act on your changes reasonably quickly. However this is something people do in their spare time, they may be busy with other aspects of their lives and not reply for several days. We will provide feedback and guidance where applicable. We want you to enjoy working with Plasma and that means we will try to help you make the most of your development time.

A reviewer accepting your code will ask themselves "Does this change make Plasma better?" if the answer is yes and you’re a first time contributor, they’ll click the merge button and might follow-up with some further changes of their own (eg for style). If you’re more experienced they’ll be a greater expectation on you to confirm to style and cover edge cases.

Getting help

If you’re stuck and the Documentation doesn’t contain the answer or clue you need, or you’re struggling to find it. Please ask for help. The Contact page of the website lists all the ways you can get in touch. In particular the Plasma Help mailing list and IRC channel are the best resources for help.

For bugs or missing information please file a bug.