Skip to content

Latest commit

 

History

History
79 lines (58 loc) · 4.95 KB

CONTIBRUTING.md

File metadata and controls

79 lines (58 loc) · 4.95 KB
Raw

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.
  • We use Universal Profile instead of account or profile.
  • We use Transaction Relay Service instead of transaction relayer or relayer.
  • We use either controller or private key instead of controller key.

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.

Page Headers

  • Every markdown file should have a description set within the Docusaurus Head Metadata to deliver improved descriptions within search engine entries.
  • Every documentation page must come with the Docusaurus Markdown Header's properties sidebar_position and sidebar_label to determine a strict order and title for the content.

File Links

  • Internal pages within the docs folder are referenced using relative redirections that end with .md. This way, link correctness can be checked within the build process of the webpage and is not affected by sidebar restructures.
  • Global pages within the src/pages folder are referenced as relative link without file ending.

Upon merging, rearranging, or removing pages, a reference must be created in the redirects register of the docusaurus.config.js file. This way, SEO entries can be updated and links will automatically redirect users to the new page.

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.

Page Metadata

---
sidebar_label: 'Feature Requests'
sidebar_position: 3
description: 'LUKSO ecosystem feature requests: developer events, hackathons, grants.'
---

Page Links

[Global Page](`./install-up-browser-extension`)
[Internal Documentation Page](`../standards/indroduction.md`)