Skip to content

Latest commit

 

History

History
120 lines (76 loc) · 7.66 KB

contributing-guide.md

File metadata and controls

120 lines (76 loc) · 7.66 KB
description cover coverY
Welcome to Hedera documentation contributing and style guide! Ways you can contribute below⬇:
../.gitbook/assets/28_ultraviolet (1) (1).jpg
31

Contributing & Style Guide

CONTRIBUTING GUIDE#contributing-guide
STYLE GUIDE#style-guide

Contributing Guide

Create new issues and pull requests

If you find something that needs to be updated or would like to publish additional content to the docs site you may do so by the following methods:

  • Log an issue
    • You may submit an issue directly on the hedera-docs repository
  • Create a pull request
    • Fork the repository and submit a pull request that includes the suggested updates

Note: Issues and pull requests will be reviewed by the Hedera team.

Hedera Improvement Proposal (HIP)

Have a new feature request for consensus or mirror nodes? Looking to submit a standard or informational guide for the Hedera ecosystem? Submit a Hedera Improvement Proposal that will be reviewed and evaluated by the Hedera Team. These improvement proposals can range from core protocol changes to the applications, frameworks, and protocols built on top of the Hedera public network and used by the community. To view all active and pending HIPs, check out the HIP website.

  1. Fork the hedera-improvement-proposal repository here.
  2. Fill out this HIP template.
  3. Create a pull request against hashgraph/hedera-improvement-proposal main branch.

Note: Which category should you make the HIP? See hip-1 for details on the HIP process or watch the following video tutorial.

{% embed url="https://www.youtube.com/watch?v=Gbk8EbtibA0" %} Hedera Improvement Proposals
by Developer Advocate: Michael Garber {% endembed %}

Style Guide

Capitalization

{% hint style="info" %} Key Point: Use standard American capitalization. Use sentence case for headings. {% endhint %}

Follow the standard capitalization rules for American English. Additionally, use the following style standards consistently throughout the Hedera developer documentation:

  • Follow the official capitalization of Hedera products, services, or terms defined by open-source communities, e.g., Hedera Consensus Service, Hedera Improvement Proposal, and Secure Hashing Algorithm.
  • Capitalize each instance of network names mainnet, testnet, and mirrornet only when preceded by Hedera, e.g., Hedera Mainnet, Hedera Testnet, and Hedera Mirrrornet.
  • Do not use all-uppercase or camel case except in the following contexts: in official names, abbreviations, or variable names in a code block, e.g., HBAR, HIPs, or SHA384.
  • You should revise any sentence starting with lowercase word stylization to avoid creating a sentence with a lowercase word.

HBAR

When referring to the Hedera native currency, use the singular form of the noun HBAR. For example:

  • "I bought 10 HBAR yesterday"

Do not use the plural form of the noun as this style rule applies even when referring to multiple units of HBAR.

tinybars

When referring to fractions of HBAR, use the plural form tinybars. For example:

  • "I will transfer 1,000 tinybars from my account to yours"

Do not use the singular form of the noun as any reference should be plural since one HBAR is equal to 100,000 tinybars.

Abbreviations

{% hint style="info" %} Key Point: Use standard American and industry-standard abbreviations, e.g., NFT for non-fungible token. Avoid internet slang. {% endhint %}

Abbreviations include acronyms, initialisms, shortened words, and contractions. In most contexts, the technical distinction between acronyms and initialisms isn't relevant; it's OK to use the phrase acronym to refer to both.

  • An acronym is formed from the first letters of words in a phrase/name but pronounced as if it were a word itself:
    • WAGMI for We're All Gonna Make It
    • DAO for Decentralized Autonomous Organization
  • An initialism is from the first letters of words in a phrase, but each letter is individually pronounced:
    • KYC for Know Your Customer
    • IPFS for InterPlanetary File System
  • A shortened word is just part of a word or phrase, sometimes with a period in the end:
    • Dr. for **** doctor
    • etc. for et cetera

Note: Some abbreviations can be either acronyms or initialisms, depending on the speaker's preference—examples include FAQ and SQL. In some cases, the pronunciation determines whether to use a or an.

Long and short versions of a word

The short versions of the words are not abbreviations; if you use them, you don't need to put a period after them—for example:

  • application and app
  • synchronize and sync

If you're unsure whether a word is an abbreviation or a shortened version of a word, look in this list of resources. If that doesn't settle the issue, use the speaking test: if you speak the short version as a word (This is a demo version of the product), you can usually treat it as a word and not an abbreviation.

Don't create abbreviations

Use recognizable and industry-standard acronyms and initialisms. Abbreviations are intended to save the writer and the reader time. If the reader has to think twice about an abbreviation, it can slow down their reading comprehension.

Make abbreviations plural

Treat acronyms, initialisms, and other abbreviations as regular words when making them plural—for example, APIs, SDKs, and IDEs.

When to spell out a term

In general, when an abbreviation is likely to be unfamiliar to the audience, spell out the first mention of the term and immediately follow with the abbreviation in parentheses, for example:

  • Miner Extracted Value (MEV)
  • elliptic-curve cryptography (ECC)

For all subsequent mentions of the term, use the abbreviation by itself. If the first mention of a term occurs in a heading or title, you can use the abbreviation and then spell out the abbreviation in the first paragraph that follows the heading or section title.

In some cases, spelling out an acronym doesn't help the reader understand the term. For example, writing out a portable document format doesn't help the reader understand what a PDF document is.

Note: The following acronyms rarely need to be spelled out: API, SDK, HTML, REST, URL, USB, and file formats such as PDF or XML.