This repository contains a curated directory of open source software (OSS) projects and their associated artifacts. Artifacts include git repositories, npm packages, smart contracts, Open Collective collectives, accounts used for managing grant funds, and more. Groups of related projects are organized into collections.
The OSS Directory serves as the "source of truth" for the projects and collections that are discoverable on Open Source Observer.
While the directory may never be complete, it is actively maintained. We welcome community contributions of new projects and collections, as well as updates to existing entries.
This directory is a public good, free to use and distribute. We hope it serves the needs of researchers, developers, foundations, and other users looking to better understand the OSS ecosystem!
Currently the main way to contribute is by submitting a pull request. You can update any .yaml
file under ./data/
or submit a new one. Fork this repository, commit your changes, and open a pull request from your fork to this repository.
Detailed instructions are available in the latest docs.
If you are adding a new project, please make sure to include a unique project name to identify the project and at least one GitHub url. In most cases, we adopt the GitHub organization name as the project name. Our project naming conventions are described in more detail here - please try to follow them!
Submissions will be validated to ensure they conform to the schema and don't contain any artifacts that are already in the directory. If you are unsure or have additional questions about contributing, please open an issue or message us on Discord.
You can install dependencies with pnpm
.
pnpm install
Our GitHub actions CI will reject any contributions that do not conform to the schema defined in ./src/resources/schema
.
To check for validation errors locally, run
pnpm run validate
We have also published this repository as a library that you can use in your own projects. This is useful if you want to build a tool that uses the data in this repository or perform your own custom analysis.
We have libraries for JavaScript and Python. We don't store the entire dataset with the package. Under the hood, this will clone the repository into a temporary directory, read all the data files, validate the schema, and return the objects. This way, you know you're getting the latest data, even if the package hasn't been updated in a while.
Note: These do not work in a browser-environment
Install the library
npm install oss-directory
# OR yarn add oss-directory
# OR pnpm add oss-directory
You can fetch all of the data in this repo with the following:
import { Project, Collection, fetchData } from "oss-directory";
const data = await fetchData();
const projects: Project[] = data.projects;
const collections: Collection[] = data.collections;
We also include functions for casting and validating data:
validateProject
validateCollection
safeCastProject
safeCastCollection
Install the library
pip install oss-directory
# OR poetry add oss-directory
You can fetch all of the data in this repo with the following:
from ossdirectory import fetch_data
from ossdirectory.fetch import OSSDirectory
data: OSSDirectory = fetch_data()
projects: List[dict] = data.projects;
collections: List[dict] = data.collections;
The directory is organized into two main folders:
./data/projects
- each file represents a single open source project and contains all of the artifacts for that project.
./src/resources/schema/project.json
for the expected JSON schemaname
../data/collections
- each file represents a collection of projects that have some collective meaning (e.g. all projects in an ecosystem).
./src/resources/schema/collection.json
for the expected JSON schemaname
.Sometimes you need to make a bunch of changes all at once. We have a framework that supports 2 types of such changes:
🚨⚠️ Note: Please use this sparingly. In the current setup, all upstream dependents of this package will break anytime there is a schema change. This is because older versions of the library will try to get the latest data from the main branch and break when validating it against an older schema ️️🚨⚠️
All files under ./data
must conform to schemas defined in ./src/resources/schema
.
If you want to change the schema, you'll need to write a migration:
src/resources/schema/
src/migrations/
folder, exporting functions that migrate each file type.src/migrations/index.ts
.pnpm migrate
.pnpm validate
to make sure your migration adheres to the schema. We will not accept any PRs where the data does not conform to the schemas.package.json
. If you don't do this, you'll break all downstream dependents, because they're fetching the latest from GitHub.The framework will run migrations in sequence, so you are guaranteed that your data is valid as of the previous version. Note: we currently only support migrating in one direction (and not reverting)
If you need to make a wide-ranging change that does not affect the schema, use these steps to script the change
src/transformations/
folder, exporting functions that transform each file type.src/transformations/index.ts
.pnpm transform --name <transformName>
pnpm validate
to make sure your migration adheres to the schema. We will not accept any PRs where the data does not conform to the schemas.We've created a schema for making project attestations with EAS. These attestations create an onchain link between a GitHub repo and its blockchain addresses (ie, that smart contracts and contract factories under its control).
You can view the schemas here:
optimism-goerli: Schema 168
optimism: Schema 86
You can make a series of attestations about a project by running the following:
ts-node src/scripts/optimism-attestation.ts data/projects/P/PROJECT.yaml optimism # OR optimism-goerli
Make sure you have .env
file that contains your PRIVATE_KEY
for an account with some ETH on the appropriate network.