This project powers the sweet animated Globe shown on the GitHub homepage. Code is maintained by the Marketing Platform Services and Site Design teams.

💻 Development

Using GitHub Codespaces is the recommended way to get this project up and running. It will install all the required dependencies and set the correct Node.js version (currently 18.17.1).

Running the Globe standalone

If you want, you can run the server on its own. Just make sure to test your changes on dotcom as well (see below):

$ npm start

Then visit http://localhost:8082.

Running the Globe on Dotcom

This will allow you to test the Globe within the actual Dotcom homepage.

1. Open a Codespace for the Globe and run the server with:

npm start

2. In the Codespace, change the port visibility of the Globe URL to public (private to org won't work with the CSP setup).

3. Open another Codespace for Dotcom and run it with the GLOBE_SERVER_URL environment variable set to the URL from the previous step:

GLOBE_SERVER_URL=public_url_from_globe_codespace... script/server

4. Enable the home_page_globe feature flag on the Dotcom Codespace:

$ bin/toggle-feature-flag enable home_page_globe

5. Visit http://github.localhost.

Debugging WebGL

If you wish to grab the WebGL context for debugging purposes, you can (both on .com and in this repo) get the WebGL context by pasting the following lines into the Console:

let canvas = document.querySelector('.js-globe-canvas');
let context = canvas.getContext('webgl2');

You could then, for example, trigger a WebGL context loss:

context.getExtension('WEBGL_lose_context').loseContext();

Debugging timestamps

We are using github/time-elements to create the relative time string on the hover cards. The custom webcomponent is included on Dotcom and only included here in devDependencies.

For testing the globe without Dotcom, uncomment import '@github/time-elements' in data-info.js to include it in the local bundle.

🚀 Deployment

This project is bundled as an NPM package and consumed on dotcom.

When you are ready to release a new version, create a new GitHub Release with the desired version number. Once the release is created, a GitHub Action will automatically publish the package to the NPM registry.

Once the new version is released, you'll want to go back to dotcom and bump the package version. You can use npm to do this:

# [on dotcom]
$ npm install @github/webgl-globe@<version> -w npm-workspaces/marketing-platform-services

Changes on the package version should be visible in Marketing Platform Services's package.json on Dotcom. Now, make sure to commit your changes ☺

# [on dotcom]
$ git add .
$ git commit -m 'Bump @github/webgl-globe'

When you're ready to deploy your changes, follow the typical Dotcom deployment process.

⎌ Rollback

If you've shipped a bad version of the Globe, the simplest way to roll back your changes is to use git revert.

Then you'll need to create a new GitHub release with a new version number, update it on dotcom, and deploy it (see 🚀 Deployment section above).

📈 Data Service

Curious about how the data makes its way into the globe? Check out the Data Service Overview doc.