opensource-website

The opensource-website project is the code and data behind opensource.newrelic.com generated by Gatsby.

About

This project is made up of a few components:

React code, components, and page templates built primarily in MDX
Static data for each open source project listed and promoted on the site, including:
- project metadata in the data/projects directory
- project stats in the data/project-stats directory
- markdown content in the data/project-main-content directory
Static pages that promote New Relic's engagement in open standards and highlight specific features and collections in New Relic's open source capabilities.
Automation to handle:
- updating dynamic data in the project stats and project metadata directories
- building the static pages
- deploying the site to a static hosting platform

Architecture

Design Choice: Project stats automation commits will appear out of sync

Every few hours as based on this configuration, a GitHub Action executes some automation rebuild the stats content of this site for each project in the src/data/projects directory.

That automation does a few things:

Retrieve the latest stats from GitHub for each project registered in the projects directory using the GitHub v3 and v4 API's
Write that data to the staging/develop branch
Selectively write the develop commit to the production/master branch
Kick off builds to both the staging and production environments without revisioning the sites

This was chosen so that functional changes in the develop branch could be tested, reviewed, and merged intentionally while automated content updates would be kept up-to-date in both branches.

The consequence of this choice is that the commit to the develop branch is not the same identifier as the commit to the master branch for precisely the same change. In the case of a PR, from staging to production, the commit histories will appear (in those areas) out of sync, without generating a merge conflict.

Two commits for the same change isn't optimal, but it's the choice the original maintainers made. Feel free to criticize (and suggest a better solution) in an issue.

Build and Deploy

This project utilizes Amplify for the hosting environment, and we've decided to employ a modified GitFlow workflow for branch management. This allows us to drive our staging and production sites from branches.

How this works:

develop is the default branch and represents the staging site. Commits (either from PR or directly to the branch) will trigger a deploy to the staging website.
- One the site is somewhat "stable", ideally all new work will take place in feature/... and fix/... branches, which are PR'ed to the develop branch.
master is our stable production branch and represents the production site. Commits must be initiated via PR's from develop -> master, and the strategy should be to rebase and merge for a cleaner view into the production history (and it will be easier to tell what's in develop vs master). This will trigger a deploy to the production website.

Our GitHub Actions automation will pick up commits to these branches and act accordingly to build and deploy the site.

In summary, feature/fix -> develop -> master eventually becomes the flow, and automation (via Actions) handles build/deploy behind the scenes.

Final Note: PRs that are opened from a branch in this repo (not forks) will generate preview links on Amplify automatically.

Contributing project data

The process to contribute new data or update existing data to opensource.newrelic.com is the same.

Fork this repository.
Add/update the two project metadata files (described below) to your forked opensource-website repository.
Submit a Pull Request back to this project containing your new or updated files.
If/when your PR is accepted, the automation in this project will populate a related file in the src/data/project-stats directory, build the site, and deploy a new version of the code (including your project's new data) to opensource.newrelic.com.

To add your project to opensource.newrelic.com, you must include the following two metadata files. To accept and merge a PR, we check that these files are present, and if you're submitting an update, that at least one of these files has been changed.

1. Project metadata (JSON)

The JSON file contains the base information about the project detail pages, as well as the project search/exploration page.

File format: src/data/projects/[GITHUB_ORG_NAME]-[GITHUB_REPO_NAME].json

Example: src/data/projects/newrelic-nr1-github.json

Template: examples/projects.json

2. Project metadata (MDX)

This MDX file contains the markdown and optional React components that populate the left-hand column of a project detail page.

File format: src/data/project-main-content/[GITHUB_ORG_NAME]-[GITHUB_REPO_NAME].mdx

Example: src/data/project-main-content/newrelic-nr1-github.mdx

Template: examples/project-main-content.mdx

Open source license

This project is distributed under the Apache 2 license.

Getting started

Ensure that you have Git and NPM installed. If you're unsure whether you have one or both of them installed, run the following commands. (If you have them installed, these commands return a version number; if not, the commands aren't recognized.)

git --version
npm -v

Execute the following command to clone this repository and run the code locally against your New Relic data:

npm install
npm start

Open http://localhost:8000/ in your preferred, modern browser.

Support

New Relic has open-sourced this project. This project is provided AS-IS WITHOUT WARRANTY OR DEDICATED SUPPORT. Issues and contributions should be reported to the project here on GitHub.

We encourage you to bring your experiences and questions to the Explorers Hub where our community members collaborate on solutions and new ideas.

Community

New Relic hosts and moderates an online forum where customers can interact with New Relic employees as well as other customers to get help and share best practices. Like all official New Relic open source projects, there's a related Community topic in the New Relic Explorers Hub. You can find this project's topic/threads here:

https://discuss.newrelic.com/t/opensource-newrelic-com/104943 (Note: This URL is subject to change before GA)

Issues / enhancement requests

Submit any issues and enhancement requests in the Issues tab of this repository. Please search for and review the existing open issues before submitting a new issue.

Contributing code

Contributions are encouraged! If you submit an enhancement request, we'll invite you to contribute the change yourself. Please review our Contributors Guide.

Keep in mind that when you submit your pull request, you'll need to sign the CLA via the click-through using CLA-Assistant. If you'd like to execute our corporate CLA, or if you have any questions, please drop us an email at opensource+opensource-website@newrelic.com.

jonathanpdx/opensource-website