Skip to content

Contributors' Guide

Jump to bottom
PeterWAWood edited this page Mar 4, 2016 · 1 revision

#Introduction

The main purpose of the Red/Code repository is a central place that is easy enough to find for newcomers to view some Red code examples, demos, libraries and apps. Newcomers will have a wide range of experience but, as Red grows in acceptance, we should expect that the majority of visitors to the repository will not have been exposed to Red or the languages that inspired it.

As a result, an effort needs to be made to keep contributions as readable as possible. That is not to say that code should be simplistic. Far from it, contributed code should be concise and elegant to demonstrate the expressiveness of Red. A few notes to explain intricate or dense code either in comments or a separate document that would aid comprehension is all that is needed. Failing that a simple warning that along the lines of "this code uses advanced techniques" would be helpful.

#Inclusion Criteria

There are both general inclusion criteria applicable to all contributions and specific inclusion criteria depending on the type of contribution.

##General Inclusion Criteria

  1. It is the submitter's work and the submitter can assert their copyright over the work or the submitter can show that they are licensed by the copyright owner to distribute the work.

  2. It follows the Red Coding Style Guide.

  3. The code demonstrates Red as it is best used.

  4. The code is concise, yet clear.

  5. The code works and is robust.

##App Inclusion Criteria

  1. The App can be easily built from the supplied source and supporting files.

  2. The App will run without the need for the user to install any software libraries.

##Script Inclusion Criteria

  1. The Script is in a single file that can either be run in the Red console or compiled.

##Showcase Inclusion Criteria The purpose of Red/Showcase is to demonstrate that a wide range of professional quality apps can easily be built with Red. The Red Team will select appropriate, high quality apps and scripts to be highlighted in the Showcase.

##Library Inclusion Criteria

  1. The Library does not require the installation of third party libraries unless it is a wrapper to an external library thought of as essential in its field (e.g. ImageMagick, ZeroMQ, OpenCV). The underlying library must be licensed under a library that is compatible with Red's own licensing.

  2. The API of the Library should be documented. In the case of wrapper libraries, the documentation required is an explanation of the mapping between the wrapper and the underlying third-party library. (A link to the API documentation of the underlying third party library should be included in the documentation).

#Submission Process

If you have an App, Script or Library that you would like to submit for inclusion in Red/Code follow this process.

  1. Check with the Red Team using the Gitter red/code channel that features and functions of your App, Script or Library would complement those already included in Red/Code.

  2. Submit a pull request for your App, Script, or Library. (See below for details).

  3. The pull request will be evaluated by the team against the inclusion criteria.

##Pull Requests for Apps The pull request for an App should be in the form of a folder with the name of the script. The folder should contain:

  • A source sub-folder which contains the complete source of all components of the App.
  • A resources sub-folder that contains any resources needed in building or running the App. (This can be further sub-divided if the author wishes).
  • A docs folder which includes a readme file that introduces the App and describes how to build and run it. Other docs can be included in the folder. It would be particularly helpful if the author could provide some explanatory commentary on the App's code especially the overall code structure and any more advanced Red coding techniques used.
  • A test folder than includes a suite of Quick-Test tests for the App. If a set of tests cannot be provided, some other evidence must be presented to show the correctness and robustness of the scripts.

##Pull Requests for Scripts The pull requests for a Script should include three files:

  • The Script source code.
  • A brief introduction of the Script followed by a short set of instructions for running and/or compiling the Script. This should be prepared in Github Markdown. The file should be named -readme.md.
  • A set of Quick-Test tests to demonstrate that the code works and is robust. The file should be named -test.red (or .reds). If a set of tests cannot be provided, some other evidence must be presented to show the correctness and robustness of the Script.

##Pull Requests for Libraries The pull requests for a Script should include four files (or folders):

  • The Library source code.
  • A brief introduction of the script followed by a short set of instructions for using and/or compiling the Library. This should be prepared in Github Markdown. The file should be named -readme.md.
  • An API for the Library in GitHub Markdown. The file should be named -api-docs.md. (A folder of API docs may be submitted if the author prefers).
  • A set of Quick-Test tests to demonstrate that the code works and is robust. The file should be named -test.red (or .reds). If a set of tests cannot be provided, some other evidence must be presented to show the correctness and robustness of the Library. ((A folder of tests may be submitted if the author prefers).
Clone this wiki locally