First off, thank you for your interest in Muddle! We, your fellow contributors, welcome contributions of all kinds and types from anyone anywhere. Whether you want to ask a question, report a bug, help work on the Muddle language (or related software), help with documentation, translation, or something else, there is a place for you.
In addition to this document please read and follow the Code Of Conduct and Attestation. If you will submit contributions of code or documentation please also read GNU Coding Standards: https://www.gnu.org/prep/standards/. Reading through this information helps to set basic ground rules, both social and technical, and make sure that everyone is on the same page.
It's important to keep communication lines open. Please discuss major changes and enhancements that you wish to make in advance with your fellow contributors.
Mailing Lists - Join the mailing lists to stay informed and discuss all things Muddle.
IRC - Chat in real-time with other muddlers in #muddle on irc.freenode.net.
First you will need to set up the git version control system. Your GNU/Linux distro has probably already packaged it for easy installation.
Read through the Attestation document and run the commands mentioned in there to set up your name and email address.
Be sure to review the information in the rest of this page, then
make your changes and commit locally, using git commit
--signoff
to add your Signed-off-by
to
each commit.
Once ready, use git format-patch origin/master
to
generate patches for your commits. Email those to the mailing list for review.
If you have write access to the repository and there is no feedback about the proposed change within a reasonable period of time (at least 24 hours depending on the nature of the change) feel free to push it to the repository (silence = consent.)
We use the coding style from the GNU Coding Standards. GNU Indent can be used to style your code appropriately. A summary of the options corresponding to that style are:
-l79 Set maximum line length for non-comment lines to 79.
-bap Enter a blank lines after function bodies.
-bbo Break long lines before boolean operators.
-bl Put braces on line after if, etc.
-bli2 Indent braces by 2 spaces.
-bls Put braces on the line after struct declaration lines.
-cp1 Put comments to the right of #else and #endif statements in column 1.
-cs Put a space after a cast operator.
-di2 Put variables in column 2.
-hnl Prefer to break long lines at the position of newlines in the input.
-i2 Set indentation level to 2 spaces.
-ip5 Indent parameter types in old-style function definitions by n spaces.
-lp Leave space between '#' and preprocessor directive.
-nbad Do not force blank lines after declarations.
-nbc Do not force newlines after commas in declarations.
-ncdb Do not put comment delimiters on blank lines.
-nce Do not cuddle } and else.
-ndj Comments after declarations are treated the same as comments after other statements.
-nfc1 Do not format comments in the first column as normal.
-nfca Do not format any comments.
-nprs Do not put a space after every '(' and before every ')'.
-nsc Do not put the '*' character at the left of comments.
-nsob Do not swallow optional blank lines.
-pcs Insert a space between the name of the procedure being called and the '('.
-psl Put the type of a procedure on the line before its name.
-saf Put a space after each for.
-sai Put a space after each if.
-saw Put a space after each while.
How to style your code is not the only thing covered in the GNU Coding Standards. Please consult the Standards for complete details.
Documentation should be written using Pandoc's extended version of Markdown: http://pandoc.org/MANUAL.html#pandocs-markdown
Line length should be set to 70 characters. To ensure that all
documentation is styled consistently, run your documentation
through Pandoc once it is written and have it convert it to its own
Markdown format. Include the options -f markdown -t markdown
--columns=70 --wrap=auto
.
Aside from the differences in documentation format, the information in the GNU Coding Standards for documentation is still relevant and should also be followed.