chore(docs): update dependencies and event types docs (#2894)

ccerv1 · web-flow · commit 558e8eae4dd7 · 2025-01-29T14:56:33.000Z
diff --git a/apps/docs/docs/references/event.md b/apps/docs/docs/references/event.md
@@ -27,64 +27,110 @@ All sources of event data are associated with a unique `event_source`. We are ad
 
 Event types are used to classify activities that relate to a given artifact namespace. The following event types are currently supported:
 
-### COMMIT_CODE
+### Code Events
 
-Represents a commit made to a code repository. This event is used to track changes in the source code over time.
+These events track activities related to source code management and collaboration:
 
-### CONTRACT_INVOCATION_DAILY_COUNT
+#### COMMIT_CODE
 
-Represents the daily count of contract invocations. This event is used to track the frequency of contract interactions on the blockchain.
+Represents a commit made to a code repository. This event is used to track changes in the source code over time.
 
-### CONTRACT_INVOCATION_DAILY_L2_GAS_USED
+#### FORKED
 
-Represents the total gas used in contract invocations on Layer 2 networks on a daily basis. This event helps track the resource consumption of contract executions.
+Represents the event when a repository is forked. This event is used to track the distribution and branching of the source code.
 
-### CONTRACT_INVOCATION_SUCCESS_DAILY_COUNT
+#### RELEASE_PUBLISHED
 
-Represents the daily count of successful contract invocations. This event is used to measure the success rate of contract executions on the blockchain.
+Represents the publication of a new release version of the software.
 
-### FORKED
+#### STARRED
 
-Represents the event when a repository is forked. This event is used to track the distribution and branching of the source code.
+Represents the starring of a repository by a user. This event is used to track the popularity and user interest in the repository.
 
-### ISSUE_CLOSED
+### Issue Events
 
-Represents the closing of an issue in a repository. This event is used to track the resolution and management of reported issues.
+These events track the lifecycle of issues in a repository:
 
-### ISSUE_OPENED
+#### ISSUE_OPENED
 
 Represents the opening of a new issue in a repository. This event is used to track new problems or feature requests reported by users.
 
-### ISSUE_REOPENED
+#### ISSUE_CLOSED
+
+Represents the closing of an issue in a repository. This event is used to track the resolution and management of reported issues.
+
+#### ISSUE_REOPENED
 
 Represents the reopening of a previously closed issue in a repository. This event is used to track the reoccurrence or unresolved status of issues.
 
-### PULL_REQUEST_CLOSED
+#### ISSUE_COMMENT
 
-Represents the closing of a pull request in a repository. This event is used to track the finalization and rejection of proposed code changes.
+Represents a comment made on an issue in a repository.
 
-### PULL_REQUEST_MERGED
+### Pull Request Events
 
-Represents the merging of a pull request into the main branch of a repository. This event is used to track the integration of code changes.
+These events track the lifecycle of pull requests:
 
-### PULL_REQUEST_OPENED
+#### PULL_REQUEST_OPENED
 
 Represents the opening of a new pull request in a repository. This event is used to track proposed changes to the codebase.
 
-### PULL_REQUEST_REOPENED
+#### PULL_REQUEST_CLOSED
+
+Represents the closing of a pull request in a repository. This event is used to track the finalization and rejection of proposed code changes.
+
+#### PULL_REQUEST_MERGED
+
+Represents the merging of a pull request into the main branch of a repository. This event is used to track the integration of code changes.
+
+#### PULL_REQUEST_REOPENED
 
 Represents the reopening of a previously closed pull request in a repository. This event is used to track the reconsideration of proposed code changes.
 
-### STARRED
+#### PULL_REQUEST_REVIEW_COMMENT
 
-Represents the starring of a repository by a user. This event is used to track the popularity and user interest in the repository.
+Represents a comment made during the review of a pull request.
 
-## NPM Events
+### Onchain Events
 
-:::warning
-This section is currently in development.
-:::
+These events track blockchain-related activities:
+
+#### CONTRACT_INVOCATION_DAILY_COUNT
+
+Represents the daily count of contract invocations. This event is used to track the frequency of contract interactions on the blockchain.
+
+#### CONTRACT_INVOCATION_SUCCESS_DAILY_COUNT
+
+Represents the daily count of successful contract invocations. This event is used to measure the success rate of contract executions on the blockchain.
+
+#### CONTRACT_INVOCATION_DAILY_L2_GAS_USED
+
+Represents the total gas used in contract invocations on Layer 2 networks on a daily basis. This event helps track the resource consumption of contract executions.
+
+### Financial Events
+
+These events track financial transactions:
+
+#### GRANT_RECEIVED_USD
+
+Represents the receipt of a grant in USD equilvalent; currently only available for sources listed in [oss-funding](https://github.com/opensource-observer/oss-funding).
+
+#### CREDIT
+
+Represents an incoming financial transaction or credit to an account; currently only available for Open Collective.
+
+#### DEBIT
+
+Represents an outgoing financial transaction or debit from an account; currently only available for Open Collective.
+
+### Dependency Events
+
+These events track package dependencies:
+
+#### ADD_DEPENDENCY
+
+Represents the addition of a new dependency to a project.
 
-All NPM events are associated with a unique NPM package. The following NPM events are currently supported:
+#### DOWNLOADS
 
-- Downloads: A snapshot of the number of downloads for an NPM package on a given date.
+Represents the number of downloads for a package on a given date according to the package manager's public data.
diff --git a/apps/docs/docs/references/impact-metrics/dependencies.md b/apps/docs/docs/references/impact-metrics/dependencies.md
@@ -8,11 +8,7 @@ sidebar_position: 5
 OSO tracks the dependency graph among projects in a collection or ecosystem. A **dependency** is a software package, module, or project that another project requires to function properly. Conversely, a **dependent** is a project that includes a specific package as its dependency. These metrics can highlight the usefulness of a given open source software project to other projects in the ecosystem.
 :::
 
-:::warning
-These metrics are currently in development.
-:::
-
-## Direct vs. Indirect Dependents
+## Dependency Types
 
 ---
 
@@ -21,83 +17,49 @@ Dependents can be categorized as:
 - **Direct Dependents**: Projects that directly include the parent package in their list of dependencies.
 - **Indirect Dependents**: Projects that rely on the parent package through an intermediary package. For example, if Package A depends on Package B, and Package B relies on Package C, then Package A is an indirect dependent of Package C.
 
-## Developer Dependencies
+## Data Sources
 
 ---
 
-Many package managers, such as npm and Crates, distinguish between production code dependencies and **developer dependencies** that are only needed for local development and testing.
-
-Below is an example of an npm `package.json` file with developer dependencies:
+OSO indexes software dependencies using multiple data sources:
 
-```
-"name": "my_package",
-"version": "1.0.0",
-"dependencies": {
-  "my_dep": "^1.0.0",
-  "another_dep": "~2.2.0"
-},
-"devDependencies" : {
-  "my_test_framework": "^3.1.0",
-  "another_dev_dep": "1.0.0 - 1.2.0"
-}
-```
+1. **GitHub Software Bill of Materials (SBOMs)**
+   - Extracted via [GitHub’s SBOM API](https://docs.github.com/en/code-security/supply-chain-security/understanding-your-software-supply-chain/exporting-a-software-bill-of-materials-for-your-repository)
+   - Includes direct and indirect dependencies
+   - Does not support all languages, but is largely complete for JavaScript/TypeScript, Python, Rust, and Go.
+2. **Package Metadata and Historical Events**
 
-## Constraints on Dependency Analysis
-
----
+   - Retrieved from the [deps.dev](https://deps.dev) public dataset.
+   - Used to map package versions to their maintainers and track add/remove events between packages.
+   - Covers major package registries (npm, PyPI, Crates.io, Go modules).
+   - Includes dependency depth charts up to 10 levels deep; we typically only use the first 3 levels.
 
-For Open Source Observer, we've set the following constraints for our dependency analysis:
+3. **Downloads from Package Registries**
 
-1. Only direct dependents are considered, excluding indirect ones.
-2. Dependency analysis is restricted to specific collections or the union of specific collection sets. This ensures a more manageable indexing process and a clearer understanding of critical package relationships within an ecosystem.
+   - Fetched by API from npm and from public datasets for PyPI and Crates.io.
+   - Track downloads and fetch metadata from select package registries
+   - Artifacts must be listed in a project's OSS Directory file in order to have these metrics indexed.
 
-Without such constraints, certain packages might appear as indirect dependents or dependencies for a vast majority of open source projects.
+4. **OSO Public Datasets**
+   - OSO provides SQL-based access to indexed dependency data in `oso_production.sboms_v0`
+   - Maintainer repositories are tracked in `oso_production.package_owners_v0`
 
-## Example
+Here is a [tutorial](../../tutorials/dependencies) on how to work with OSO dependency datasets.
 
-> Note: This is a hypothetical example. Real-world examples based on actual dependency graphs will be added soon.
-
-Consider a collection of "Ethereum Developer Tools" with projects like `ethers` and `wagmi` and another collection called "Optimism Applications" with projects like `velodrome-finance` and `zora`. If `velodrome-finance` depends on `ethers`, and `zora` depends on both `ethers` and `wagmi`, then `ethers` has two dependents, and `wagmi` has one.
-
-```
-Ecosystems: Ethereum Developer Tools & Optimism Applications
-    |
-    |----> Project: ethers
-    |          |
-    |          |----> Dependent: velodrome-finance
-    |          |----> Dependent: zora
-    |
-    |----> Project: wagmi
-               |
-               |----> Dependent: zora
-```
-
-## Dependent Metrics
+## Limitations
 
 ---
 
-In addition to mapping projects and their dependents, we also capture the following data about a project's dependents:
-
-### Current Dependents
+Dependency data is not always complete. Here are some of the limitations:
 
-Count of dependent projects as of the most recent indexing run. These may also be referred to as "downstream dependencies" or "reverse dependencies".
+- Published packages may change maintainers, which can cause discontinuities in the dependency graph.
+- Some languages are not well-supported by the data sources.
+- We rely on various sources, which have different indexing and data ingestion schedules. The latest changes may not always be reflected in the OSO production data.
 
-### Current Dependencies
-
-Count of dependencies as of the most recent indexing run. These may also be referred to as "upstream dependencies".
-
-### Active Developer Dependents
-
-Count of active developers of all dependent projects in the same collection.
-
-### Active User Dependents
-
-Count of active users of all dependent projects in the same collection.
-
-### Fees Dependents
-
-Total sequencer fees of all dependent projects in the same collection.
+## Contributing
 
 ---
 
-To contribute new metrics, please see our guide [here](../../contribute-models/data-models)
+There is a vast amount that can be done on top of these data sources!
+
+To contribute new metrics and models, please see our guide [here](../../contribute-models/data-models)
diff --git a/apps/docs/docs/references/impact-metrics/package.md b/apps/docs/docs/references/impact-metrics/package.md
