Contributing & Style Guide
Learn how to submit a demo application, create pull requests, or log issues in the Hedera Contributing Guide.
We value every form of contribution, no matter how small. In this guide, you will find steps on submitting an issue, creating a pull request, submitting a demo application, creating Hedera Improvement Proposals (HIPs), and adhering to our style guide. Thanks in advance for your contributions!
If you've identified a problem in the documentation or have a suggestion for additional content, you can submit an issue. Follow these steps:
- 1.Navigate to the Repository: Visit the
hedera-docsrepository on GitHub.
- 2.Open the Issues Tab: Find the "Issues" tab near the top of the repository page, next to "Code" and "Pull Requests". Click on it.
- 3.Create a New Issue: Click the "New Issue" button to open a form where you can detail the problem or suggestion.
- 4.Fill Out the Form: Give your issue a title and a detailed description. Be as clear and concise as possible to ensure we fully understand the issue. If applicable, include screenshots or code snippets.
- 5.Submit the Issue: After filling out the issue, click the "Submit new issue" button. We'll review your issue and take appropriate action.
If you'd like to propose changes directly to the documentation, you can submit a pull request. Here's how:
- 2.Clone the Forked Repository: Clone the forked repository to your local system and make changes. Be sure to follow the repository's coding and style guidelines.
- 3.Commit Your Changes: Once you've made your changes, commit them with a clear, detailed message describing the changes you've made.
- 4.Push Your Changes: Push your committed changes to your forked repository on GitHub.
- 5.Submit a Pull Request: Back in the
hedera-docsrepository, click the "Pull Requests" tab and then the "New pull request" button. Select your forked repository and the branch containing your changes, then click "Create pull request".
- 6.Describe Your Changes: Give your pull request a title and describe the proposed changes. This description should make it clear why the changes should be incorporated.
- 7.Submit the Pull Request: Click the "Create pull request" button to submit it. We'll review your proposed changes and, if they're approved, merge them into the repository.
By logging issues and creating pull requests, you're helping us make the Hedera documentation better for everyone. We appreciate your contributions and look forward to collaborating with you!
Note: The Hedera team will review issues and pull requests.
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 the Hedera public network and used by the community. To view all active and pending HIPs, check out the HIP website.
Hedera Improvement Proposals by Developer Advocate: Michael Garber
If you have a demo application that you'd like to share, we encourage you to follow the steps outlined below to ensure your application is showcased accurately.
- 2.Within the issue, please include the following details:
- 1.Demo application name: The official name of your demo application. This is how it will be listed on the demo applications page.
- 2.Developer/Maintainer name and GitHub username: Your name or the person maintaining the demo application. This ensures we know who to contact for any future updates or questions regarding the application.
- 3.Link to the demo application GitHub repository: Please provide a link to the public GitHub repository where your demo application is hosted. This allows the Hedera community to access and review your application.
- 3.Submit your issue once you've provided the required details within the issue. Our team will review your submission, and if approved, your demo application will be added to our list.
Remember, the aim is to showcase applications that demonstrate the potential and functionality of Hedera in various use cases. Clear, concise, and well-documented code is highly appreciated.
Thank you for your valuable contribution to the Hedera community! We look forward to reviewing your demo application.
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.
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 equals 100,000 tinybars.
Follow the American English spelling standard. This means that words should follow the American English conventions, employing 'z' instead of 's' in words such as 'decentralized,' 'realized,' and 'organized.'
- Use 'color' instead of the British English 'colour.'
- Use 'analyze' instead of the British English 'analyse.'
- Use 'organization' instead of the British English 'organisation.'
Use an American English dictionary or a recognized American English style guide to ensure consistency and accuracy throughout the text. Tools like Grammarly or spell checkers set to American English can assist in maintaining this standard.
When presenting steps or instructions within the documentation, the following guidelines should be observed:
Ordered Steps (Numbered List): If the steps must be followed in a specific sequence, use a numbered list to present the order clearly. This ensures that readers understand the progression and importance of each step.
- 1.Clone repo.
cdinto the cloned directory.
Unordered Steps (Bulleted List): If the order of the steps is not crucial to the outcome, use bulleted points. This provides flexibility for readers to approach the tasks as they prefer.
- Choose a color.
- Select a size.
- Identify a preferred style.
Adhering to these guidelines will ensure readers' clarity and ease of understanding, allowing them to follow instructions effectively, whether in a precise sequence or with more flexible options.
Key Point: Use standard American capitalization. Use sentence case for headings.
- 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.
The Oxford comma is the comma used immediately before the coordinating conjunction ("and" or "or") in a list of three or more items. In our written content, the use of the Oxford comma is required to maintain clarity and prevent ambiguity.
Example: "The team consists of product managers, developers, designers, and writers."
By consistently applying the Oxford comma, we ensure that the meaning of lists is clear, especially when individual items contain commas themselves. This standard reflects our dedication to ensuring clear and accurate communication in all of our documentation.
Key Point: Use standard American and industry-standard abbreviations, e.g., NFT for non-fungible tokens. Avoid internet slang.
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
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.
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.
Treat acronyms, initialisms, and other abbreviations as regular words when making them plural—for example, APIs, SDKs, and IDEs.
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.