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 projects to showcase or builder tools

Help to add good projects or builder tools. Please note the different guidelines for adding showcases or builder tools.

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 or builder tools 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 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 errow [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.

Should I commit the yarn.lock file?

No, please do not commit your yarn.lock file it is an auto-generated file that should be handled only by yarn.

Shouldn't yarn.lock be in the ignore file then?

No, as this will have side effects with dependencies used by the project itself. (Even if you prefer npm)

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.