:ref:`topics-overlays` are used to define the commands supported by a given application, service, or operating system. Commands are defined as a function.
1) Define a Module
------------------
The first step is to create a new module in which functions will be defined.
..code-block:: python
# module_name.py
from ..commands import Command
For overlays that represent an operating system, the ``command_exists()`` function is required:
..code-block:: python
def command_exists(name):
return name in MAPPINGS
2) Define Command Function
--------------------------
The purpose of each function is to provide an interface for instantiating a :py:class`scripttease.library.commands.base.Command` instance. The example below is taken from the ``posix`` module.
The arguments and any specific keyword arguments are automatically used by the parser, but also serve as a simple interface for programmatic use.
Each function *must* also accept ``**kwargs`` and should set a default for ``comment`` as above.
3) Add Functions to the Mapping
-------------------------------
The final step adds the function to the mapping. This makes it available to the command factory.
..code-block:: python
# module_name.py
# ...
MAPPINGS = {
'mkdir': mkdir,
}
For overlays that represent an operating system, ``MAPPINGS`` is required -- in addition to ``command_exists()`` above. For commands that are specific to service or application, the name of the dictionary may be anything that is appropriate. For example, ``DJANGO_MAPPINGS``.
Additionally, for an operating system overlay, you may wish to import other mappings and incorporate them into ``MAPPINGS``.
We welcome contributions to this and any of `our open source projects`_. There are a number of ways to participate and contribute. See :ref:`contact`.
.._our open source projects: https://develmaycare.com/products/
Reporting Issues
----------------
Perhaps the easiest way to contribute is to submit an issue. If you have found a bug or error in the documentation, please submit a request. See :ref:`contact`.
..important::
Do **not** report security issues using the issue tracker. Instead, send an email to security@develmaycare.com with details on the issue you've discovered.
Submitting Feature Requests
---------------------------
Although we reserve the right to decline new features, we welcome all feature requests. See :ref:`contact`.
Testing and Quality Control
---------------------------
Testing involves using Script Tease in real life or in development. Feel free to report any issues you find, or to improve the unit tests.
Pull Requests
-------------
Pull requests are welcome. Such requests should be associated with an issue. We may ignore pull requests that do not have a corresponding issue, so create an issue if one does not already exist.
Translations
------------
TODO: Translations help make Script Tease available to more people around the world.
Blogging
--------
You may help spread awareness of Script Tease by writing blog posts. We are happy to link out to reviews and tutorials from our web site. `Let us know if you've created a blog post`_ that we can share. Be sure to include a link to the post.
You may also provide us with a guest post to be included on our blog.
.._Let us know if you've created a blog post: https://develmaycare.com/contact/?product=ScriptTease
..note::
We reserve the right to proof and approve or decline all content posted on our web site.
Development
===========
TODO
Setting Up For Development
--------------------------
TODO
Style Guide
-----------
Script Tease follows `PEP8`_ and (where appropriate) the `Django style guide`_ and `JavaScript Standard Style`_.
Script Tease follows a loose form of `semantic versioning`_. The use of semantic versioning makes it clear when deprecation occurs and backward compatibility is removed. Documented incompatibilities may still exist where deprecation is not feasible (technically or financially).
.._semantic versioning: https://semver.org/
Cadence
-------
Prior to the 1.0 release, new features may be released at any time. After the 1.0 release, new features are planned for release every 3 months. Patch-level changes (to fix bugs or security issues) are always released as needed.
Long-Term Support
-----------------
Some releases may be designated as long-term support (LTS) releases. Such releases will have security and critical bug fixes applied for 6 months.
Deprecation Policy
------------------
Minor releases may deprecate features from a previous minor release. For example, if a feature is deprecated in release 1.1, it will continue to work in the 1.2 release, though warnings may be raised. However, the deprecated feature may be removed in release 1.3 and may not function as previously expected or will raise errors.
Major releases may *always* remove deprecated features.
An overlay is a collection of functions that provide an interface to command creation.
There are currently three (3) general and re-usable overlays:
- common
- django
- pgsql
And two (2) overlays that are specific to operating systems:
- posix
- ubuntu
The examples that follow instantiate command instances from an INI file. Each example is shown with the defaults. All commands support a number of :ref:`topics-configuration-common-parameters`.
Shawn Davis
4 years ago