Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
95 lines (76 loc) · 4.16 KB

CONTRIBUTING.md

File metadata and controls

95 lines (76 loc) · 4.16 KB
Raw

How to contribute

Patches are more than welcome at OpenCryptoki, be it to fix a bug or to add a new feature. To make your life, and also our life, easy there are a few steps that we need the contributors to follow.

Getting started

  • Read and study the current PKCS #11 standard.
  • Make sure you have a GitHub account
  • Submit a ticket for your issue, assuming one does not already exist.
    • Clearly describe the issue, including steps to reproduce when it is a bug.
    • Make sure you fill in the earliest version that you know has the issue.
    • In case of a bug, try to attach some logs. Enable tracing on OpenCryptoki by running export OPENCRYPTOKI_TRACE_LEVEL=<level>. For more information about trace level check the FAQ.
    • Include information from your environment (OS, gcc version, and any other related packages version).
    • In case of a new hardware token, please provide a way for us to have access to an environment that contains such hardware or a way to run automated tests through Jenkins or other similar tool.
    • In case AI assisted you to identify the issue, please state the name of the AI tool or framework.
  • Fork the repository on GitHub.

Making changes

  • Create a topic/issue branch from the master branch.

  • Please avoid working directly on the master branch.

  • If the changes are too big, please separate it into smaller, logical, commits. This will improve commit history and code review.

  • Follow the coding style guidelines.

  • Check for unnecessary whitespace with git diff --check before committing.

  • Make sure your commit messages are in the proper format and sign your patch to certify the Developer Certificate of Origin (DCO):

    Add CONTRIBUTING guideline

The CONTRIBUTING.md file describes the guidelines that every Contributor
should follow to get their code integrated into OpenCryptoki. This will
improve Contributors/Maintainers work.

Signed-off-by: YOUR_NAME <youremail@something.com>

  • AI agents MUST NOT add Signed-off-by tags. Only humans can legally certify the Developer Certificate of Origin (DCO). The human submitter is responsible for:

    • Reviewing all AI-generated code.
    • Ensuring compliance with licensing requirements.
    • Adding their own Signed-off-by tag to certify the Developer Certificate of Origin.
    • Taking full responsibility for the contribution.

  • Make sure you have added the necessary tests for your changes.

  • Run all the tests to assure nothing else was accidentally broken. If you do not have the necessary hardware to run all tests, please write it down to us, so we can manage to do the testing for you.

Attribution

When AI tools contribute to openCryptoki, proper attribution helps track the evolving role of AI in the development process. Contributions should include an Assisted-by tag in the following format:

Assisted-by: AGENT_NAME:MODEL_VERSION [TOOL1] [TOOL2]

Where:

  • AGENT_NAME is the name of the AI tool or framework
  • MODEL_VERSION is the specific model version used
  • [TOOL1] [TOOL2] are optional specialized analysis tools used (e.g., coccinelle, sparse, smatch, clang-tidy)

Basic development tools (git, gcc, make, editors) should not be listed.

Submitting Changes

  • The human submitter must sign the commits with a Signed-off-by: tag to certify the Developer Certificate of Origin (DCO), as described above. AI agents must not add this tag themselves.
  • Submit a pull request to the opencryptoki repository at https://github.com/opencryptoki/opencryptoki.
  • Include test information/results on the pull request.
  • Wait for the Maintainers feedback about your changes. Although we are always working on the project, sometimes we have our attention caught up on higher priority tasks for the project.
  • Be ready to answer any doubts that we might have about your changes, otherwise if we do not get an answer we will not be able to merge your code.

Final thoughts

  • Feel free to ask questions, there is no such thing as a stupid question, just stupid people.
  • Have fun in the process, coding is fun!