Skip to content

Latest commit

 

History

History
55 lines (39 loc) · 3.97 KB

CONTIBRUTING.md

File metadata and controls

55 lines (39 loc) · 3.97 KB

LUKSO Docs Contribution Guide

Welcome to our documentation guide for contributors. We've set up specific rules and conventions to make PR reviews more seamless and have a global way of documenting and styling things.

Naming Conventions

  • We write true/false in code brackets and lowercase without additional styling to ensure it is a boolean, not a value or constant.
  • We always refer to ERC725Y keys as data keys, so there is no confusion for readers about keys in general, for instance, controller keys, public/private keys, etc.
  • We only use bold text for keywords or phrases instead of whole sentences, as it should only highlight the most critical information.
  • We use simple present tense and 3rd person singular to describe functions and document APIs / ABIs.
  • We use simple present in headings but do not enrich them with additional styling.

Word Specification

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this repository are to be interpreted as described in RFC 2119.

Content Styling

  • We try to keep a unified look for the headings on the right navigation bar and, therefore, encourage the use of less than 35 characters so they do not split up into several rows.
  • We do not skip headline sizes. The use of ## should only be done if at least one parent headline uses only one hash sign.
  • We always write parameter names in code brackets. If there is an additional code snippet, the naming of the parameters should be equal.
  • We only use one text styling at a time and neither stack bold, italic, heading, or code formation on top of each other. Links, however, do not count as styling and can always be added.
  • We try to stick to Markdown as much as possible. We make exceptions for
    • media integrations other than pictures
    • tables bigger than 120 chars in line length
    • custom styling out of regular page content
  • We encourage the use of Docusaurus Admonitions for
    • additional information,
    • warnings, or
    • hints.
  • We encourage the use of Docusaurus Tabs if there are different
    • versions for code snippets or files,
    • outcomes regarding code execution, or
    • additional code explanations, unnecessary for the immediate implementation.

File Links

  • We use relative redirections that end with .md for all internal content within this repository. This way, link correctness can be checked within the build process of the webpage and is not affected by restructuring to subfolders in the left sidebar.

LSP Naming

  • We always write standard names beginning with an uppercase letter to distinguish them from regular descriptions.
  • We use the full standard name with a hyphen and spaces between the abbreviation and the long-written words for headings.
  • We always use the full standard name without any additional characters for explanations within the text. The abbreviation should only be excluded if the full standard name was mentioned at least once on the same page before.
  • We use the full standard name without any spaces to address the underlying smart contract directly

Examples

Name Conventions

The function retrieves an array of data keys for multiple smart contract addresses if the read-in result of the last call returned true. Otherwise, the function will return false as the given addresses do not appear to be LSP0 ERC725 Accounts.

LSP7 - Digital Asset Example

The LSP 7 Digital Asset is a token standard for fungible assets built by LUKSO. Developers can look up the LSP7DigitalAsset smart contract within the @lukso/lsp-factory.js library. Some features of the Digital Asset include more secure transfers, additional metadata, and token hooks.