The opensource-website
project is the code and data behind opensource.newrelic.com generated by Gatsby.
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 directoryproject stats
in the data/project-stats directorymarkdown 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
andproject metadata
directories - building the static pages
- deploying the site to a static hosting platform
- updating dynamic data in the
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.
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/...
andfix/...
branches, which are PR'ed to thedevelop
branch.
- One the site is somewhat "stable", ideally all new work will take place in
master
is our stable production branch and represents the production site. Commits must be initiated via PR's fromdevelop
->master
, and the strategy should be torebase and merge
for a cleaner view into the production history (and it will be easier to tell what's indevelop
vsmaster
). 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.
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 thesrc/data/project-stats
directory, build the site, and deploy a new version of the code (including your project's new data) toopensource.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.
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
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
This project is distributed under the Apache 2 license.
- 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.
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.
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)
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.
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.