All the info you need to onboard your crew at the OSS Port: showcase or find a project, make a map, or create a tour.

Getting Started

Video thumbnail for gDAvFPnNFyo

Intro to the OSS Port

Ahoy! Let Ramón from CodeSee show you the ropes at the Port!

How to list your project on OSS Port

We’re thrilled to have you in Port. It's super easy to get started, and should only take about 11 minutes.

Step 1: Getting up and running

You can put your project up on Port without having to run the app! Go ahead and check out the steps below.

If you have a javascript development environment set up already and prefer to run locally, the approach will be familiar. environment

  1. Create a fork of the OSS Port.
  2. Once on your fork's page, either press the full stop . key or replace .com in the location bar in your browser to .dev.

Now you're in the editor! Feel free to hop ahead to our contributing section.

For more information on the editor, please see their docs.

Local development (optional)

  1. Clone this repository to your machine
  2. Inside the project directory, install the dependencies using Yarn:
  3. Run the project locally:
    yarn start
  4. You can now view the project in your browser at http://localhost:8000


Step 2: List your project

  1. Follow the above setup steps
  2. Create your project's .mdx file
    1. Create a new folder inside /projects and name it the same as your GitHub handle or organization
    2. Add a new .mdx file to that folder, and give it the name of your public repo. For example,
      • if your project were:
      • you would create: /projects/Codesee-io/oss-port.mdx.
    3. Copy/paste the contents of projects/_template.mdx into that file
  3. Fill out the information — most of it is optional, but extremely helpful for potential contributors. If you opt not to include the optional content, delete it from your template.
  4. Add a 200x200 image for your organization to your folder, for example, ./projects/distributeaid/da.png
  5. Preview your changes by running yarn start
  6. When you're ready, open a PR!

Step 3: Adding a CodeSee Map to your project listing

Make it easier for contributors to onboard to your project! With a CodeSee Map, they can visualize the entire codebase, with features allowing them to explore system dependencies, add additional context to pull requests, and more.

To add a Map to your project:

  1. Sign up for CodeSee Maps (there's no commitment or cost!)
  2. Create a Map for your repo following our instructions
  3. Set your map to public!
  4. Add an entry in your project's template for the Map (see example from Distribute Aid's Shipment Tracker project):
  description: Get a quick overview of the major areas of our repo

That's it!

The CodeSee Map below is a good way to get familiar with the codebase:

CodeSee Map preview

Tag policy

Final tags are up to the maintainers of OSS Port. Your tags may be modified for the benefit of the community and to improve discoverability.

We use title-casing for tags. For example: "First Timer Friendly, Social Activism, C#, JavaScript".

How to remove your project from OSS Port

Open a PR to remove your project folder from this repository.

How to Create a Glowing Getting Started Section

Video thumbnail for Bmsbq9aDej0

How to Create a Glowing Getting Started Section

Join Ramón from CodeSee as we show off some of our favourite Getting Started Sections and seeing what's helpful!

Onboarding Into a Large Codebase

Video thumbnail for OHzaLhKiaus

3 tips for getting started with a large codebase

Join Ramón from CodeSee as we share 3 great ways to get started with a brand new codebase if you're stuck!

Looking for more helpful and inspiring developer resources?

Visit Our Blog

Built with tea and love by