Skip to content

Latest commit

 

History

History
139 lines (94 loc) · 7.15 KB

HACKING.md

File metadata and controls

139 lines (94 loc) · 7.15 KB
Raw

Table of Contents generated with DocToc

endoflife.date uses Jekyll, the static website generator. This document helps you set the codebase locally. This isn't necessary for most content changes. Follow this guide if you are making layout, design, or code changes.

Development

First, you will need to install Ruby and Bundler. Follow these instructions to install Ruby, and then run the following commands:

# Install bundler
gem install bundler

# Clone the project:
git clone --recurse-submodules git@github.com:endoflife-date/endoflife.date.git
cd endoflife.date

# Install dependencies (_Note: You must use Bundler 2 or greater_):
$ bundle install

# All of the following commands should run successfully at this point:
ruby --version
bundle --version
bundle exec jekyll --version

Build

Run the site locally:

$ bundle exec jekyll serve --host localhost --port 4000

Browse to http://localhost:4000 and you should see the site running locally. If you find any errors at this stage, check Jekyll's troubleshooting page or ask a question in the Q&A category on GitHub Discussions.

Other Jekyll commands are documented on the Jekyll website, along with the command options for the build and serve commands.

File and Directory structure

  • The layout for the products page is in _layouts/post.html
  • Product data is in the products directory.
  • Automation scripts that fetch latest releases are in the _auto directory.
  • We follow the Jekyll directory structure:
    • _includes holds partial templates, such as the content for the <head> tag.
    • assets includes CSS/JS/Logo images etc
    • _plugins holds scripts invoked by the Jekyll build code
    • _config.yml holds the Jekyll configuration, including list of plugins, exclude/include filelist, theme configuration, and plugin settings.
    • Gemfile and Gemfile.lock are package files for bundler.
  • _headers holds the template for generating a list of custom HTTP headers, in the Netlify Headers Format. A rendered version (might be dated) of the file can be seen here.
  • _redirects similarly holds the template for generating redirects from alternate URLs to main product pages, again in the Netlify format. You can see a rendered version here.
  • Rakefile configures the entrypoint for our automation scripts.
  • robots.txt is for web scraping robots.
  • humans.txt holds details about the people and tech behind the project.

Extending the Jekyll theme

The site is based on the Just the Docs Jekyll theme. Take a look at the documentation for knowing more about its configuration (beware, this configuration is for the current main branch, not for the version used by this site).

If you need to override some parts, take a look at the customization section of the documentation.

Logo

The site logo is an adaptation of An hourglass in a round icon by David Abián and Serhio Magpie. The logo is representing the concepts of time (with the hourglass) and EOL/cycles (with the colored split circle).

Derived icons for various usages, such as the web app manifest were generated using RealFaviconGenerator.net.

All icons were placed in the assets directory, except favicon.ico. The Just the Docs Jekyll theme mandates its path to /favicon.ico, and it seems a lot of browsers assume this location anyway.

Note that android-chrome-*.png icons were renamed to logo-*.png. Those icons are used in other contexts, such as on the site as a logo.

Automation

Automation is currently focused towards fetching the latest releases for a given release cycle. Scripts for this are in the _auto directory, and run using Rakefile.

All scripts should have fallback data in some form.

API

The API is just JSON files generated in the api directory by _plugins/create-json-files.rb. The API is not stable, because the key names or release names are not consistent.

API Documentation

The API Documentation is available at https://endoflife.date/docs/api and is generated from an OpenAPI Specification file located at _data/openapi.yml. The documentation is rendered Stoplight Elements.

Contributing Workflow

If you just want to add a new product or make some trivial changes, please see CONTRIBUTING.md. Else:

  • Fork the project
  • Create your feature branch (git checkout -b my-new-feature)
  • Commit your changes (git commit -am 'Add some feature')
  • Push to the branch (git push origin my-new-feature)
  • Create new Pull Request

Deployment

The code is built and deployed to Netlify under it's Open Source Plan. We use the following Netlify Features:

  • Custom HTTP Headers (_headers file)
  • Custom Redirects (_redirects file)

The build script is kept in netlify.toml.

Analytics

There are no javascript trackers or analytics on the website. Netlify Analytics enabled as an experiment. Numbers from Netlify Analytics and Google Search Usability Reports are published on the wiki

Automation

The endoflife.date project runs a bit of automation on top of GitHub Actions to automate mundane tasks. This is primarily updating the latest version of each product, wherever possible. This is documented in the wiki.

Bulk Updates

To facilitate bulk updates to the products, a script _auto/bulk-update.py is available. You only need to write in the update function to make changes to all files together.