Skip to content

Latest commit

 

History

History
139 lines (95 loc) · 7.67 KB

HACKING.md

File metadata and controls

139 lines (95 loc) · 7.67 KB
Raw

Table of Contents generated with DocToc

release-parser 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 [email protected]:khulnasoft/release-parser.git
cd release-parser

# 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 updates latest releases are in the _auto directory. Also see the release-data repository, where the updates are fetched, and the Automation page on the wiki.
  • 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 (dated) rendered version here.
  • 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 are placed in the assets directory. Our theme tries to pick the favicon from /favicon.ico, which we don't have to avoid this behaviour. However, many browsers will assume this location anyway, so we have a redirect from /favicon.ico to a PNG version instead.

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 updating the latest releases for a given release cycle against the release-data repository. Scripts for this are in the _auto directory.

API

The API is just JSON files generated in the api directory by _plugins/create-json-files.rb. The API is not yet stable, because the key names or release names are not consistent. See #2080 for a v1 release of the API.

API Documentation

The API Documentation is available at https://releaselog.netlify.app/docs/api and is generated from an OpenAPI Specification file located at assets/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).
  • Easy deploy previews.
  • Future plans to use Netlify Functions.

The build script is kept in netlify.toml.

Analytics

There are no javascript trackers or analytics on the website. Numbers from Google Search Reports are published on the wiki. The data provided by Google is for publishers, and is based on search queries that showed release-parser in the search results. Google has more details here, including limitations of this data. Rare queries are omitted by Google from this data to protect user privacy.

Automation

The release-parser 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.