Proposal To Add A SERVICES.md or similar documentation to OpenJS Projects

[bensternthal]

Proposal: Shifting Service Inventory Responsibility to Projects

As part of the STF work in 2024, the IT team conducted audits to catalog all the services that OpenJS projects rely on. However, this was documented in Google Sheets in a way that is difficult to maintain. The current approach presents several challenges:

• Lack of project ownership: Projects cannot easily update or maintain their own service lists.
• Not version controlled: The inventory is disconnected from the project repositories and their development workflows.
• Rapidly outdated: The information is already obsolete, making it unreliable.

Maintaining an accurate, up-to-date list at the foundation level (IMHO) is a losing battle. Instead, we should shift this responsibility to individual projects to ensure accuracy and timely updates

Proposal (This is a straw person and is intended to be something folks can react to)

• Projects would maintain a SERVICES.md file
• The file would contain 3rd party SASS products that the project relies on, these would be significant services not everything
• We'd ask that projects reach out to the foundation prior to engaging with a significant 3rd party sass provider (in case we have a existing arrangement, or should have an arrangement)

Below is an example of what I am thinking.

# Third-Party Services Used

This project relies on the following third-party services:

## Hosting & Infrastructure
- **Cloud Provider:** AWS (EC2, S3)
- **CDN:** Cloudflare
- **DNS Provider:** Namecheap

## Development & CI/CD
- **Code Repository:** GitHub
- **CI/CD:** GitHub Actions, Travis CI
- **Artifact Storage:** Docker Hub, NPM

## Monitoring & Security
- **Logging:** Datadog
- **Error Tracking:** Sentry
- **Vulnerability Scanning:** Dependabot

## Communication & Support
- **Email Provider:** SendGrid
- **Issue Tracking:** GitHub Issues

[ctcpip]

possibly related: expressjs/discussions#324

[mhdawson]

In terms of adoption it would be good to add some doc on the benefits to the project by doing this. Does it result in better support from Foundation, have other projects found it helpfull to their day to day work etc.

[ctcpip]

Projects should consider whether a doc like this should be exposed publicly. Meaning, it is perhaps better to live in a private repo for security reasons, though should be a low risk, as the doc should not contain any especially sensitive information.

[wesleytodd]

It would be good to loosen the suggestions a bit around "should have" and where the content lives. For example, for single repo projects, it might not be desirable to have it live in the root of the repo because then it clutters the code while also maybe needing to be added to npmignore's and stuff like that.

But generally on Express we were hoping to do this for our own benefit as maintainers to keep track of things, especially as new maintainers come into the project.

[MarshallOfSound]

Projects should consider whether a doc like this should be exposed publicly. Meaning, it is perhaps better to live in a private repo for security reasons, though should be a low risk, as the doc should not contain any especially sensitive information.

I'd be against drawing people a clear map of a projects infrastructure, in principle it shouldn't matter if people know which DNS provider, or hosting provider power certain pieces of project infrastructure but I'd rather not make it deliberately easier for folks to know what to go after 🤷

Electron already has an internal service registry for stuff we run ourselves, including CI, hosting, apps/bots etc. And I'm not sure there's a super compelling reason to share that publicly, but sharing our existing doc with the foundation seems reasonable (from my perspective, not speaking unilaterally for electron)

[tobie]

Notes from this week's CPC call:

• As some concerns were expressed around security, can we find a middle ground without disclosing too much info?
• Can we ask the security collab space about the security risks?
• Electron would be open to share this list privately but not publicly

[bensternthal]

@ruddermann we discussed this item in today's CPC call and felt it was a good topic for the security working group, can we add this to the agenda for next week?

[tobie]

CPC update: Was on agenda for previous sec working group, Ben discuss with that group and come back with a recommendation prior to next CPC call.

[mcollina]

I'm +1.

[bensternthal]

Waiting on written recommendation from @ruddermann

[ruddermann]

Howdy yall, apologies for the delay here.

I've drafted up an initial policy below. Here is a gDoc version in case folks would prefer to comment on items that way.

One of the challenges of this initial version was the flexibility that the Security Collab Space suggested that each project be given to maximize for adoption of the policy. To achieve this, the consensus of the Collab Space is that the policy should NOT be prescriptive regarding if the file is stored in a public or private repo and give each project the choice.

Since we're giving projects this flexibility, one of the things I was left wondering is flexible Robin/Ben/others would be to how they are notified about changes to the services.md file and how they would like to be informed of changes that projects were only beginning to consider. I'm looking forward to hearing folks' thoughts and feedback.

See the draft policy below:

OpenJS Third Party Services Documentation Policy

Summary

This policy establishes communications and documentation guidelines that allow the OpenJS Foundation to maintain visibility of the third party services OpenJS hosted projects are currently using or planning to in the future.

The Foundation wishes to leverage this information to:

• Identify opportunities for strategic vendor partnerships
• Provide support and guidance for vendor partnerships
• Understand development infrastructure needs across Foundation projects

This policy is intended to be structured in a way that enables the Foundation to understand and foster partnerships while respecting project autonomy and security considerations.

Policy: Notify the Foundation when considering changing existing or adding new service providers

Before engaging with a significant third-party SaaS or infrastructure provider, projects are asked to contact the OpenJS Foundation (Robin Ginn or Ben Sternthal). The Foundation may have existing arrangements or facilitate new partnerships in collaboration in with projects.

Choose one of the following approaches to engage with the Foundation:

Open for discussion:

Option 1: In your own GitHub Issue or Discussion
Option 2: Email Notification
Option 3: Create an issue in the CPC repo
Option 4: Others?...

Policy: Maintain documentation of current and future services

1. Services.md file contents and format

Each OpenJS project must maintain a services.md file that documents significant third-party SaaS products and infrastructure providers used by the project.

This information should be maintained in a simple Markdown list. The below example is illustrative and not intended to necessarily be comprehensive as each project may have additional items unique to them.

# Third-Party Services Used

This project relies on the following third-party services:

## Hosting & Infrastructure
- **Cloud Provider:** AWS (EC2, S3)
- **CDN:** Cloudflare
- **DNS Provider:** Namecheap

## Development & CI/CD
- **Code Repository:** GitHub
- **CI/CD:** GitHub Actions, Travis CI
- **Artifact Storage:** Docker Hub, NPM

## Monitoring & Security
- **Logging:** Datadog
- **Error Tracking:** Sentry
- **Dependency Management:** Dependabot
- **Security Scanning:** CodeQL

## Communication & Support
- **Email Provider:** SendGrid
- **Issue Tracking:** GitHub Issues

Important

Keep entries high-level. Do not include sensitive information such as vendor contacts, contract or license information, or specific data about the infrastructure itself.

2. Services.md storage location

The services.md file must be:

• Stored within each project's own GitHub organization
• Accessible to the OpenJS Executive Director (Robin Ginn, @rginn) and OpenJS Director of Program Management (Ben Sternthal, @bensternthal)
• The project's maintainers should not rely on automated GitHub notifications and must inform the Foundation of where their services.md is located by emailing <Ben? A leadership distro?>

Projects may choose, at their own discretion, to place this file in either a public or private repository. The level of detail expected of the services.md file is typically not sensitive and often easily discovered, however the Foundation defers to each project's preferences and governance for where the file is stored.

3. Services.md Maintenance & Notifications

• The services.md file is to be updated as necessary to remain an accurate reflection of the current state of the project.
• Under certain circumstances, such as during a transition, it may be appropriate for services.md to also contain credible plans for future or in progress changes.

To enable Foundation monitoring of service usage across projects, choose one of the following approaches:

Option 1: Repository-level watching

• Add @rginn (Robin Ginn) and @bensternthal (Ben Sternthal) as collaborators with read access to the repository containing your services.md file so they can watch the repository for changes

Option 2: Manual notification

• When making significant updates to your services.md file, notify the Foundation by mentioning @rginn and @bensternthal in the commit message or pull request

Questions and Support

For questions about this policy or assistance with implementation, please contact the OpenJS Foundation by [Contacting Ben? Opening a CPC issue? Going to the Collab Space?].

[ruddermann]

I've updated the gDoc version to incorporate feedback from @bensternthal.

I didn't see an agenda issue for the CPC meeting tomorrow, but this issue should still be tagged correctly to put it on the agenda.

[tobie]

Notes from this week's CPC call:

• @ruddermann providing us with an update on the draft policy
• Next steps are creating a PR out of the doc and having the CPC comment in the PR