Skip to content

Latest commit

 

History

History
111 lines (80 loc) · 3.98 KB

CONTRIBUTING.md

File metadata and controls

111 lines (80 loc) · 3.98 KB
Raw

Contribution guidelines

Before starting

Thanks for your interest in the Octowire framework project! There are multiple ways to help beyond just writing code:

  • Submit bug and feature requests with detailed information about your issue or idea.
  • Help fellow users with open issues.
  • Submit an update, a brand new module or a module improvement.

Contributing to the Octowire framework

Here's a short list of do's and don'ts to make sure your valuable contributions actually make it into Octowire framework's master branch. If you do not care to follow these rules, your contribution will be closed.

Code contributions

Creating a new module

Create an issue on owfmodules.skeleton with these details:

  • Module name (owfmodules.CATEGORY.NAME)
  • A short description
  • Module category (uart, jtag, spi, misc, ...)

If we accept the module, we will create a repository initiated with the owfmodules.skeleton repository.

Useful information

Use the octowire-lib library as much as possible for protocol interaction.

Initial steps

  1. Fill the README.md file
  2. Rename the category directory (uart, spi, i2c, ...)
  3. Rename the module_name.py file
  4. Rename the class
  5. Modify the setup.py file

Start coding (<module_name>.py)

  1. Update meta variable (into __init__ method)
self.meta.update({
    'name': 'Module short description',
    'version': '1.0.0',
    'description': 'Module long description',
    'author': 'Name and/or email'
})
  1. Define necessary options and advanced options if necessary (A list of dict)
self.options = [
    {"Name": "Option1", "Value": "", "Required": True, "Type": "string/int/bool",
     "Description": "Option1 description", "Default": "default value if available"},
    {"Name": "Option2", "Value": "", "Required": False, "Type": "string/int/bool",
     "Description": "Option2 description", "Default": self.config["OCTOWIRE"]["read_timeout"]},
]

# Do not erase it (it contains default advanced options)
self.advanced_options.append(
            {"Name": "adv_opt_name", "Value": "", "Required": True, "Type": "int",
             "Description": "Advanced option description", "Default": ""}
        )
  1. Implement the run method

Available type options

  • "string" -> String
  • "int" -> Integer (1337)
  • "float" -> float (1337.0)
  • "hex" -> Hexadecimal (0x1337)
  • "bool" -> Boolean (0, 1, True, False)
  • "hextobytes" -> Automatically convert Hexadecimal string (0x1337) to Bytes
  • "file_r" -> Readable file path
  • "file_w" -> Writable file path

Pull Requests

  • Write "WIP" on your PR if submitting working yet unfinished code.
  • Include only one module per pull request.
  • Always start your work on the master branch to ensure you are using the latest and most stable codebase.
  • As much as possible, make use of functions from the library (octowire-lib) and framework (octowire-framework).
  • Include verification steps on your PR message (target, environment, ...).
  • Include a short summary of what your code/module does on your PR message.

Bug fixes

  • Link any corresponding issues in the format of See #1234 in your PR description.
  • Explain in a few words how you fixed it in your PR message.

Bug reports

  • Write a detailed description of your bug and use a descriptive title.
  • Give as many details as possible about your environment.
  • Include steps to reproduce the issue, stack traces and anything that might help us fix your bug.
  • Search for your bug in open issues before opening a new issue.

Thank you for taking a few moments to read these contribution guidelines!