<p align="center">
  <img src="https://cloud.githubusercontent.com/assets/98681/24211275/c4ebd04e-0ee8-11e7-8606-061d656a42df.png" width="60" height="60">

  <h2 align="center">
     ✨🌍✨ Globe ✨🌍✨<br>
  </h2>
</p>

<img width="1552" alt="image" src="https://user-images.githubusercontent.com/257028/95641526-c2b4e680-0a57-11eb-92e0-282d50ca6376.png">

This project powers the sweet animated Globe shown on the [GitHub homepage](https://github.com/home). Code is maintained by the [Marketing Platform Services](https://github.com/github/marketing-platform-services) and [Site Design](https://github.com/github/site-design) teams.

## 💻 Development

Using [GitHub Codespaces](https://github.com/github/globe/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):

```shell
$ 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:

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

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

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

### Debugging timestamps

We are using [github/time-elements](https://github.com/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](https://www.npmjs.com/package/@github/webgl-globe) and consumed on dotcom.

When you are ready to release a new version, create a new [GitHub Release](https://github.com/github/globe/releases) 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:

```shell
# [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](https://github.com/github/github/blob/master/npm-workspaces/marketing-platform-services/package.json). Now, make sure to commit your changes ☺

```shell
# [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](https://thehub.github.com/engineering/development-and-ops/deployment/deploying-dotcom/).

## ⎌ 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](https://github.com/github/globe/blob/master/Data%20Service%20Overview.md) doc.
