Skip to main content

How to contribute to the developer portal

We wanted to build a developer portal as open and inclusive as Cardano. A portal that is in the hands of the Cardano community and can be constantly evolved by it.

For this to be successful, the portal relies on your contributions, and the fact that you are reading this text probably means that you have something to contribute, even if you are not a Developer.

If you want to install the portal on your local machine, you can jump directly to the installation instructions.

Why should I contribute?​

Build your reputation: Contributions to the developer portal will give your GitHub name and profile higher visibility as more and more people come across your work online. As visibility increases, so too will the reputation of your name and brand.

Build your confidence: Creating tutorials and showing fellow community members how to create will not only elevate your knowledge of your own skills and processes, but will also bestow you with greater confidence in your abilities as you interact with others.

As an added bonus, since everything is public, people typically pay greater attention to how well something is written or programmed. This will also afford you with an invaluable set of eyes on your contributions that will serve as a crucial peer-reviewed tool to catch errors and refine your work.

Build your resume: Each contribution you make acts as a precious notch on your belt towards career development or job searches within the Cardano ecosystem. It is also a way for people to find examples of your work and verify your abilities. By contributing to open source projects, you will not only gain a lot of valuable experience, but if your profile (or brand) reaches a certain level of attention and recognition, you are also more likely to get professional opportunities further down the line.

I got the spirit. What can I do to contribute?​

Spread the word​

Often underestimated: spread the word. For example: if someone asks you for Cardano wallets, link to the wallet showcase if they want to know about Cardano block explorers, link to the block explorer showcase.

Create issues​

Creating an issue is the first step to improving the portal. You don't even have to do the improvement yourself. You can think of it as creating a topic in a forum.

An "issue" can be anything from a simple suggestion to a fully elaborated plan with many sub-items and tasks to check off. You can also open an issue to discuss things. Like a public task manager, people can assign tasks to themselves. Create an issue now

If creating an issue in GitHub is too much for you please consider opening a topic on the Cardano Forum with a title like "Developer Portal Suggestion: your suggestion".

Improve texts​

Fix typos and improve texts, especially if you are a native speaker and have strong writing skills.

Create graphics​

If you are a talented graphic designer, you can improve various charts and diagrams. We should always use graphics that work well in both light mode and dark mode for the portal. You can also make one graphic for each.

Participate in the discussions​

If you think something is wrong or something fundamental should change, discussions are the appropriate start to find consensus. There are always ongoing discussions on how to handle or improve something. Please take part in them. Even if you are not a developer, your views are valuable:

Add a project to showcase​

Help to add good projects to the showcase section. Please note the guidelines for adding new projects:

  • It must be built on Cardano and have a real use case. For example, a forum where people can talk about Cardano is great, but not for this showcase section.
  • It has to run on Cardano mainnet.
  • It has to have a running product. (no presale, no protected pages, no coming soon messages)
  • It has to have enough community reputation.
  • It has to provide a unique value distinct from existing showcase items.
  • It has to have a stable domain name. (a random Netlify/Vercel domain is not allowed, no URL shortener, no app store links, or similar)
  • The GitHub account that adds the project must not be new.
  • The GitHub account must have a history/or already be known in the Cardano community.
  • Describe what makes your project special, avoid phrases like "the first this and that". Granular details like which project was first is tribal attribute known to cause rift and conflicts.
  • Please refrain from adding NFT projects unless they are immensely different from what is already listed in terms of utility. We can't list hundreds of NFT projects. For details please follow or take part in the discussion here. (TL;DR: we are adding winners of the CNFT Awards)
  • If you add a project with a main component of NFTs, please select "nftproject" as tag. (not "nftsupport")

Mainly the project showcase should be a place where someone new to the ecosystem can come to see what can be done. For example we agreed that projects have to have a running product today on Cardano mainnet, no promises, no pre-sales, no coming soon pages. We also don't aim to map out a future ecosystem.

Adding projects to the showcase section will require creating a pull request.

Add tools to builder tools​

Help to add useful tools to the builder tools section. Please note the guidelines for adding new builder tools:

  • It is an actual builder tool that adds value to Cardano developers.
  • It has a stable domain name (a random for example, Netlify/Vercel domain is not allowed)
  • The GitHub account that adds the builder tool must not be new.
  • The GitHub account must have a history/or already be known in the Cardano community.

A builder tool is a software application or platform that enables users to create, modify, and deploy software applications, or other digital products on Cardano.

Adding tools to the builder tools section will require creating a pull request.

Create/improve documentation​

Documentation can constantly be improved, and there are gaps in the developer portal. In particular, the stake pool operator section needs a lot of work. To create and improve documentation, you should install the portal on your local machine.

Create/improve tutorials​

Apart from documentation, tutorials are an excellent way to explain things. If you already have a website with tutorials, consider moving them to the Developer Portal. To create and improve documentation, you should install the portal on your local machine.

Create pull requests​

A pull request is a proposal to change something on the developer portal. It can be a small change like fixing a typo or a complete category with hundreds of new files. Pull requests must be reviewed.

Review pull requests​

If you have an excellent technical understanding and mistakes catch your eye, you can review pull requests. You should have made contributions before please read here for more details.

Frequently Asked Questions​

How are pull requests reviewed?​

Pull requests must be approved by three reviewers to be merged. They are always merged into the staging branch. https://staging-dev-portal.netlify.app reflects the state of the current staging branch.

Later, the changes are pushed from staging to the main branch. This requires another pull request. (For this reason, there is always a small delay between staging and production).

How to become a reviewer?​

You should have an excellent technical understanding, great ethics and have already contributed to the developer portal. Your GitHub account should have some reputation. If you are unsure, just participate in the discussions.

How to get added to the contributor list?​

We don't currently have a specific metric that determines who gets included on the contributor list. You should at least have made a strong mark on a category or have contributed consistently over a long period. Participate in the discussions to determine this.

How to connect with the developer community?​

Cardano developers and stake pool operators spread across many different platforms. We aim to provide a complete overview.

If you are interested in connecting with people from the Developer Portal, either visit the Discord or open a thread in the forum.

Installation​

To contribute to the Cardano developer portal, you must first install it locally. We have chosen Docusaurus 2, a modern static website generator, as the underlying software.

Requirements​

  • Node.js version >= 16.14 (which can be checked by running node -v). You can use nvm for managing multiple Node versions on a single machine installed.
  • Yarn version >= 1.5 (which can be checked by running yarn --version). Yarn is a performant package manager for JavaScript and replaces the npm client. It is not strictly necessary but highly encouraged.
  • On macOS you also need Xcode and Command Line Tools.

Local development​

To get a local development environment, clone the repository, navigate into the developer-portal folder, install dependencies, and start the development server. Most changes are reflected live without having to restart the server. By default, a browser window will open at http://localhost:3000.

git clone --depth 1 https://github.com/cardano-foundation/developer-portal.git
cd developer-portal
yarn install
yarn start
Limitations of the development build

The development mode will have minor features not working. For example, only blurry images in the responsive images on showcase and tools, search limitations, and some data has fake values because of performance reasons.

Create at least once a production build (see below) as this pulls missing files.

Production build​

yarn build

Use this command instead of yarn start to generate static content into the build directory that can be served using any static content hosting service.

Project structure​

The portal is structured as follows. (See the Project structure rundown below for details)

developer-portal
├── blog
│   ├── 2021-01-07-january.md
│   ├── 2021-02-03-february.md
│   └── *.md
├── changelog
│   └── source
│       ├── 2021.8.0.md
│       ├── 2021.12.0.md
│       ├── 2021.16.0.md
│       └── *.md
├── docs
│   ├── fund-your-project
│   ├── get-started
│   ├── integrate-cardano
│   ├── native-tokens
│   ├── operate-a-stake-pool
│   ├── stake-pool-course
│   ├── transaction-metadata
│   └── *.md
├── examples
│   ├── cli
│   |   ├── dotnet
│   │   │   └── *.cs
│   |   ├── js
│   │   │   └── *.js
|   |   └── python
│   │       └── *.py
|   └── wallets
│       ├── dotnet
│       ├── js
|       └── python
├── scripts
│   ├── cip.ts
│   ├── rust-library.ts
│   ├── token-registry.ts
│   └── *.md
├── src
│   ├── css
│   │   └── custom.css
│   ├── data
│   │   ├── builder-tools
│   │   │   └── *.png
│   │   ├── showcase
│   │   │   └── *.png
│   │   ├── builder-tools.js
│   │   └── showcases.js
│   └── pages
│       ├── styles.module.css
│       └── index.js
├── static
│   └── img
├── docusaurus.config.js
├── package.json
├── README.md
├── sidebars.js
└── yarn.lock

Project structure rundown​

  • /blog/ - Contains the blog Markdown files for the developer spotlight.
  • /changelog/source/ - Contains the changelog data split by months into Markdown files.
  • /docs/ - Contains the Markdown files for the docs. Customize the order of the docs sidebar in sidebars.js.
  • /examples/ - Contains example projects for the Markdown files in the docs. The structure is not final and will likely change in the future
  • /scripts/ - Contains scripts to fetch auto generated content like CIPs, Rust Library, Token Registry.
  • /src/ - Non-documentation files like pages or custom React components. You don't have to strictly put your non-documentation files in here, but putting them under a centralized directory makes it easier to specify in case you need to do some sort of linting/processing.
    • /src/data/builder-tools - Screenshots for the builder tools section.
    • /src/data/builder-tools.js - Definition file for the builder tools section.
    • /src/data/showcase - Screenshots for the showcase section.
    • /src/data/showcase.js - Definition file for the showcase section.
    • /src/pages - Any files within this directory will be converted into a website page.
  • /static/ - Static directory. Any contents inside here will be copied into the root of the final build directory.
  • /docusaurus.config.js - A config file containing the site configuration.
  • /package.json - A Docusaurus website is a React app. You can install and use any npm packages you like in them.
  • /sidebar.js - Used by the documentation to specify the order of documents in the sidebar.

Known problems that may arise​

We list here problems you may run into when running the developer portal locally.

Minimum Node.js version not met​

Problem: yarn start throws the error [ERROR] Minimum Node.js version not met :(.
Solution: use the node version listed below requirements. If you have different node versions installed for different projects, nvm is a neat tool to deal with it. You can switch versions with for example nvm use 16.

Problem: yarn start throws the error [ERROR] Sidebars file at "developer-portal/sidebars.js" failed to be loaded..

Solution: you need to run at least once yarn build as this pulls missing files into your folder, which is then referenced by sidebars.js.

Problem: yarn start throws the error [ERROR] Error: Sidebar category Token Registry has neither any subitem nor a link. This makes this item not able to link to anything..

Solution: you need to run at least once yarn build as this pulls missing files into your folder, which is then referenced by sidebars.js.

Other questions​

Various other questions and answers.

Anything I can do to make sure my pull request will not break on the staging/production server?​

Yes, please always do a yarn build before submitting a pull request. It will find many more issues than yarn start.

Is there any style guide? Do we have editorial guidelines?​

Yes, both still work in progress but please see style guide and editorial guidelines.

Should I commit the yarn.lock file?​

No, please do not commit your yarn.lock file: this represents a software baseline and should be updated only at regular intervals by site maintainers.

I committed yarn.lock to my PR branch: what do I do?​

Assuming:

  • origin refers to your local fork
  • upstream refers to the cardano-foundation repository

First, do one of these in your the working root directory of your fork (to restore an unmodified yarn.lock):

  • ... from your working fork's staging branch (if you've created your PR branch from there):
    • git checkout staging -- yarn.lock
  • ... from the staging branch of your fork itself:
    • git checkout origin/staging -- yarn.lock
  • ... from the official repository:
    • git checkout upstream/staging -- yarn.lock

Then commit to reverse the changes you've made. For example:

  • git commit -m 'reverting to unmodified yarn.lock'

The same technique can be used to revert modifications to other portal files. For more help, see the popular thread Remove a modified file from pull request.