While Next.js can handle static sites, we've had a few issues with it, notably a performance hit at runtime and some bugginess around routing and SSR. Gatsby being fully intended for high-performance static sites makes it a great technical fit for the Shields frontend. The `createPages()` API should be a really nice way to add a page for each service family, for example.
This migrates the frontend from Next.js to Gatsby. Gatsby is a powerful tool, which has a bit of downside as there's a lot to dig through. Overall I found configuration easier than Next.js. There are a lot of plugins and for the most part they worked out of the box. The documentation is good.
Links are cleaner now: there is no #. This will break old links though perhaps we could add some redirection to help with that. The only one I’m really concerned about `/#/endpoint`. I’m not sure if folks are deep-linking to the category pages.
There are a lot of enhancements we could add, in order to speed up the site even more. In particular we could think about inlining the SVGs rather than making separate requests for each one.
While Gatsby recommends GraphQL, it's not required. To keep things simple and reduce the learning curve, I did not use it here.
Close#1943Fix#2837Fix#2616
This implements the configuration mechanism I described in #2621. The heavy lifting is delegated to [node-config](https://github.com/lorenwest/node-config) with a minor assist from [dotenv](https://github.com/motdotla/dotenv).
`private/secret.json` has been replaced with environment variables and/or `config/local.yml`. See `doc/server-secrets.md`.
Three main goals:
1. In the front end:
a. Show form fields and automatically assemble badge URLs (#701)
c. Group together examples for the same service
b. Show deprecated services
2. Make it easy to changing the schema of `examples`, thanks to 100% validation. One challenge with frameworks is that when there are typos things fail silently which is pretty unfriendly to developers. The validation should really help with that. (This caught one bug in AUR, though I fixed it in #2405 which landed first.)
3. Produce a service definition export for external tool builders. (#776)
4. Build toward harmony between the front-end data structure and the `examples` key in the service classes. I aliased `staticPreview` to `staticExample` which starts this process.
The old format:
- Lacked a consistent machine-readable representation of the fields.
- Flattened multiple examples for the same service were flattened.
- Excluded deprecated services.
The new format improves a few things, too:
- It cleans up the naming. Since this file evolved over time, the names were a bit muddled (i.e. what was an example vs a preview).
- It duplicated information (like `.svg`). (I can imagine dropping the `.svg` from our badge URLs someday, which would make the URLs easier to read and maintain.)
- For a human reading the YAML file, providing the static example as a deconstructed object is more readable.
Here are a couple snippets:
```yml
- category: build
name: AppVeyorCi
isDeprecated: false
route:
format: '([^/]+/[^/]+)(?:/(.+))?'
queryParams: []
examples:
- title: AppVeyor
example: {path: /appveyor/ci/gruntjs/grunt, queryParams: {}}
preview: {label: build, message: passing, color: brightgreen}
keywords: []
- title: AppVeyor branch
example: {path: /appveyor/ci/gruntjs/grunt/master, queryParams: {}}
preview: {label: build, message: passing, color: brightgreen}
keywords: []
- category: downloads
name: AmoDownloads
isDeprecated: false
examples:
- title: Mozilla Add-on
example: {path: /amo/d/dustman, queryParams: {}}
preview: {path: /amo/d/dustman, queryParams: {}}
keywords: [amo, firefox]
```
* move gh-badges files out of /lib
As far as possible, this is just moving files
around and updating paths however there are 2
functional changes in this commit:
- remove use of lib/register-chai-plugins.spec
in badge-cli.spec.js
- remove use of starRating()
in text-measurer.spec.js
* update service tests that use colorscheme.json
* split package.json in two
* clean up import
* don't hard-code path
* start a changelog
* put a license file in the package dir
* re-organise documentation 📚
* don't pack test files
* remove favicon from Makefile
* give package its own test command
* link the docs better in README
Instead of centralizing examples, specify them from within a service.
* Avoid duplication in service loading + refactor
* Avoid duplication in URLs, rename uri -> url in BaseService
I rewrote the frontend in React using a module bundler. It's matched feature-for-feature with the current frontend, with only slight changes in the styling. I did not fuss about making the styling identical; the badge popup looks particularly different.
This makes the front end much easier to develop. I'm really looking forward to implementing #701, to which this paves the way.
This makes light use of Next.js, which provides webpack config and dev/build tooling. We’ll probably replace it with create-react-app or our own webpack setup because unfortunately it comes with a lot of runtime overhead (the build is 400k).
Let’s open new issues for bugs and features, and track other follow-ups here: https://github.com/badges/shields/projects/1
This pull request sets us up to generate the badge examples dynamically from data and code.
Right now, try.html is still checked in, mostly for the benefit of reading this diff, though it should be removed on the next pass to avoid unnecessary complexity at merge time.
* Add template for secret.json
- Move to faster and lighter Alpine base image
* Update documentation
* Update documentation
* Fix Github token config for secret.json
* Extend env file for Docker runtime configuration
- Update documentation
- Add gh_token for GH personal access token to secret template
* Change http to https in infoSite
* Update .dockerignore
* Update .gitignore
* Update dockerignore
* Remove ENV directive from Dockerfile
- Environment is needed at runtime, not at buildtime
* Docker: contain secret.json in private/
- Incorporates fix from 7c8b0e3d
* Use localhost in example env
* Use baseUrl in GitHub redirect
* Move GH personal token retrieval up
- To remove duplicate Promise.then()
* Typo in shields.example.env
- Build index.html at deploy time
- Update corresponding documentation references
- Since index.html is untracked, git add needs -f
- Clarify gh-pages generated commit message
- Improve Makefile dependencies related to website generation
As discussed in #936, tracking the index.html causes makes PRs longer / noisier
and causes extra merge conflicts. More importantly, it causes contributors to
inadvertently edit the wrong file, which causes extra work (#949) or
contributions to be lost (#898).
Since there's no need for index.html in development (everything uses try.html) a
logical solution is to generate and commit the index.html at deploy time.
Recording compiled or generated files in a deploy commit is a reasonable
practice for git-based deploys (Heroku, gh-pages, and others).
The old version of this was slightly "unsafe" for my taste, in that it depended
on the local copy of gh-pages (if it existed) and master. The new version just
replaces gh-pages with master + the new commit.
Closes#936.
Fixes#954 (the PR).
