Welcome to Our Contributor Community!

We're thrilled that you're interested in becoming a part of our thriving community. We believe in fostering an environment where everyone feels welcome and is able to contribute. To ensure the well-being of our community, we adhere to a Code of Conduct. Please take a moment to read it thoroughly before making any contributions.

Before you begin working on an issue, please familiarize yourself with the project's contribution guidelines in their CONTRIBUTING.md. This will provide you with an understanding of the project's process.

How Can You Contribute?​

There are numerous ways to contribute to TBD. Here are some suggestions to get started. If you have any questions or need help, feel free to reach out to us on Discord.

• Stars on GitHub: If you resonate with our mission and believe in a decentralized web, consider starring our projects on GitHub! 🌟
• Ask Questions: Your questions not only help us improve but also benefit the community. If you have a question, don't hesitate to ask it in Discord.
• Contribute to the Codebase: We welcome any and all contributors to help us push the web forward by building a decentralized ecosystem.
• Participate in Community Events: We host a variety of community events on our Discord stage every month, ranging from Show & Tells to brainstorming sessions. Got an event idea or wish to host one? Post it in our #community-events forum. The DWN project also host office hours every Tuesday. All events will be posted in our events calendar in Discord.
• Write a Blog Post: Are you passionate about writing? Share your expertise and insights with our community! We welcome your contributions to our blog section on the TBD Developer website. Propose blog topics in our #general channel on Discord. We can't wait to read and share them with the community!
• Propose a New Project: We believe in community-driven innovation. If you have an idea for a project that helps Web5, tbDEX, or the TBD open source ecosystem, we'd love to talk with you about our Incubation Program.
• Improve Documentation: Good documentation is key to the success of any project. You can help improve the quality of our existing docs or add new pages.
• Showcase Your Work: Working on a project or written a blog post recently? Share it with the community in our #share-what-you-do channel.
• Give Feedback: We're always looking for ways to improve. If you have feedback on our website or docs, feel free to use our feedback template.
• Give Shoutouts: Is there a project you love or a community/TBD member who's been especially helpful? Feel free to give them a shoutout in our #general channel.
• Spread the Word: Help us reach more people by sharing TBD's projects, website, and/or Twitter/X.

Good First Issues​

We understand that contributing to open source for the first time can be daunting. That's why we've highlighted some repositories with good first issues. Be sure to check the repo's contribution guidelines and don't hesitate to ask any questions on Discord or on the issue ticket itself. We're looking forward to celebrating your first commit with you! 🎉

• Developer Website
• Web5-JS
• SSI-Service
• SSI-SDK
• SSI-Playground
• SSI-admin-ui
• DWN-Server
• DWN-SDK-JS

New Open Issues​

We've highlighted some repositories with new open issues to help you get started. If you don't see a project here that you're interested in, Check out our other repos here.

• Developer Website
• Web5-JS
• SSI-Service
• SSI-SDK
• SSI-Playground
• SSI-admin-ui
• DWN-Server
• DWN-SDK-JS

Contributing Code Snippets​

Our Code Snippet system allows for updates in one place while ensuring code is runnable and tested, enhancing our tutorials and guides.

Steps to Create a Code Snippet​

1. Create Your Test: Navigate to site/__test__ and create a test file named to match the functionality of the code, e.g., how-to-create-did.test.js.

   note

   Use the .test. naming convention for Vite to recognize and run these tests.

2. Tag Your Snippets: In your test files, use :snippet-start: and :snippet-end: tags to mark the beginning and end of a code snippet. Immediately name your snippet after the :snippet-start: tag.

   test('createDidDht creates a DID with did:dht method', async () => {
     // :snippet-start: createDidDht
     const didDht = await DidDhtMethod.create({ publish: true });
     // ... rest of the code ...
     // :snippet-end:
   });
   

3. After creating your snippets, run the command pnpm run shnip. This will generate a folder called snippets and create a directory structure similar to where the file is.

4. In the generated folder you'll find the generated file named as functionName.snippet.js (or the respective file extension). For example, the above snippet will be createDidDht.snippet.js.

To use the snippet in your documentation(.mdx file), you're going to use the Shnip component. The Shnip component will dynamically import your snippets for you. Here's an example on how to use it:

// if it's a multi language doc, you'll need to specify it with the LanguageSwitcher component

This is how you can add a generated code snippet and an inline hardcoded snippet into the doc:

```js
<Shnip
  snippets={[{ name: 'assignVcJwt', language: 'JavaScript' }]}
  inlineSnippets={[
    {
      code: `
            val signedVcJwt = "eyJ0eXAiOiJKV1QiLCJhbGciOiJFZERTQSIsImtp..."
      `,
      language: 'Kotlin',
    },
  ]}
/>

To display inline code in a language different from the tab's primary language, use codeLanguage. If codeLanguage is unspecified, it defaults to language. Example: For Bash in a JavaScript tab, set language: 'JavaScript', codeLanguage: 'bash'

<Shnip
  inlineSnippets={[
    {
      code: `
npm install @web5/credentials
npm install @web5/dids
      `,
      language: 'JavaScript', // The tab's context.
      codeLanguage: 'bash', // Snippet's actual language
    },
  ]}
/>

MDX and JSX struggle to parse line breaks. For controlled line breaks in inline snippets, use breakLineAt with line numbers in an array. Example: To break after lines 1 and 5, set breakLineAt: [1, 5]

<Shnip
  inlineSnippets={[
    {
      code: `
import { VerifiableCredential, PresentationExchange } from "@web5/credentials";
class SwiftiesFanClub {
  constructor(level, legit) {
    // indicates the fan's dedication level
    this.level = level; 
    // indicates if the fan is a genuine Swiftie
    this.legit = legit; 
  }
}
      `,
      breakLineAt: [1, 5],
    },
  ]}
/>

To add titles to code snippets, use the title prop. Example: title: 'Issuer.js' adds a title to the snippet.

<Shnip
 snippets={[{ name: 'assignVcJwt', language: 'JavaScript', title: 'Issuer.js' }]}
  inlineSnippets={[
    {
      code: `
import { VerifiableCredential, PresentationExchange } from "@web5/credentials";
class SwiftiesFanClub {
  constructor(level, legit) {
    // indicates the fan's dedication level
    this.level = level;
    // indicates if the fan is a genuine Swiftie
    this.legit = legit;
  }
}
      `,
     title: 'Issuer.js',
    }
  ]}
/>

Using Prepend tags​

To enhance our documentation with executable code snippets that remain synchronized with the latest test cases, we've introduced prepend tags. These tags allow you to specify setup code, such as import statements, that should be automatically included at the beginning of designated snippets. This ensures that our documentation reflects accurate and executable code examples.

Directory Structure Configurations​

• match: Mimics the test file's directory structure.
• byLanguage: Organizes snippets into language-specific directories.
• organized: A structure that organizes by language and function name. For example: /snippets/js/createDidDht and /snippets/kt/createDidDht
• flat: Places all snippets directly within the snippets folder.

Usage​

Prepend tags are used to mark blocks of code that should be prepended to one or more snippets. Here's how to use them:

1. Marking Prepend Blocks: In your test files, use the :prepend-start: and :prepend-end: tags to denote the beginning and end of a code block that should be prepended. Immediately after the :prepend-start: tag, specify the names of the snippets that should include this block, separated by spaces.

// :prepend-start: snippetName1 snippetName2
import { SomeLibrary } from 'some-library';
// Additional setup code...
// :prepend-end:

2. Associating with Snippets: Ensure that the snippet names provided after the :prepend-start: tag match exactly with the names used in your :snippet-start: tags. This association is case-sensitive and must be precise to ensure the correct prepend blocks are included.

Generating Snippets with Prepend Blocks​

After marking your prepend blocks and associating them with snippets, run the pnpm shnip command. This process will automatically prepend the specified blocks to the snippets and generate the output in the configured snippets directory.

Example​

// :prepend-start: createDidDht
import { DidDhtMethod } from '@web5/dids';
// :prepend-end:

// :snippet-start: createDidDht
const didDht = await DidDhtMethod.create({ publish: true });
// :snippet-end:

The generated snippet will include the import statement at the top, ensuring the snippet is executable and reflects the necessary setup:

import { DidDhtMethod } from '@web5/dids';

const didDht = await DidDhtMethod.create({ publish: true });

CLI​

• Clear Command: pnpm shnip clear
• Structure Flag: pnpm shnip --structure byLanguage

Caveats for Code Snippets​

• The code snippet function names need to be unique, these names are what is used to generate/name the snippet files.
• These tests are only testing the code snippets. There are more thorough tests that actually test the SDK.

Running tests​

You can use the following scripts to run the tests:

• pnpm test to run tests
• pnpm test:watch to run tests in dev mode

License​

When contributing to projects under TBD you agree to license your contributions under Apache License 2.0.

Join the Community

Connect with us everywhere.

GitHub

Submit a PR or open an issue

View

Discord

Engage with fellow community members

Join

Twitter/X

Follow us for news and updates

Follow