Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
94 lines (69 loc) · 3.49 KB

CONTRIBUTING.md

File metadata and controls

94 lines (69 loc) · 3.49 KB

Contributing Guide

How to contribute

This is a collaborative effort. We welcome all contributions submitted as pull requests.

(Contributions on wording & style are also welcome.)

Bugs

A bug is a demonstrable problem that is caused by the code in the repository. Good bug reports are extremely helpful – thank you!

Please try to be as detailed as possible in your report. Include specific information about the environment – version of Lume, Deno, Operating System, etc, and steps required to reproduce the issue.

Pull Requests

Good pull requests – patches, improvements, new features – are a fantastic help. Before create a pull request, please follow these instructions:

  • One pull request per feature. If you want to do more than one thing, send multiple pull request.
  • Write tests.
  • Run deno fmt to fix the code format before commit.
  • Document any change in the CHANGELOG.md.

AI code

Avoid the use of genAI tools to produce code. And if you really need to use that, please specify which parts are generated by AI in your pull request.

Local development

To use a local version of Lume in your site for testing purposes, change the lume/ import in the import map to the local folder of Lume. For example:

{
    "imports": {
-       "lume/": "https://deno.land/x/lume@2.5.0/",
+       "lume/": "../lume/",

Alternatively, use Lume CLI for a simpler process:

  • Run lume local --save in your local Lume clone to set the current directory as the local Lume path.
  • Run lume local in your project folder to update the lume/ import to the local path.

Changelog

Lume has a CHANGELOG.md file to document all changes for each version. The file follows the specs defined at Keep a Changelog.

Please, document your changes in the latest unreleased version inside one of the allowed sections (Added, Changes, Removed, Fixed). Create the section it if doesn't exist. Include the identifier of the issues and/or pull request at the end: (i.e. - Fixed URL generation #123). Then run deno task changelog to format the file and generate the links to GitHub.

Testing

Run deno task test to run all Lume tests. If you only want to run a single file, run deno task test [path]. For example deno task test tests/esbuild.test.ts.

The tests consist on a bunch of miniwebsites that are build and the result must match with the previous snapshot.

Example with icons test

Let's see the test file for the icons plugin at tests/icons.test.ts:

  • getSite returns a Site instance with the src folder configured to the icons folder (resolved to tests/assets/icons).
  • Then, we can configure the site. For this test, we import and register the icons plugin.
  • The function build(site) builds the site without writing the files on disk but saving result on memory.
  • Finally, we use the function assertSiteSnapshot to check if the result matches with the snapshot.
  • The snapshots, stored in the tests/__snapshots__ folder, contains an array with the generated content of all pages and other info that we want to check. If the new content doesn't match with the snapshot, the tests fail.
  • If you make some changes that generate a different output:
    • Fix your changes to generate the same expected output.
    • Or run deno task test:update to update the snapshot with the new output.
    • Or run deno task test tests/icons.test.ts -- --upate to update the snapshot of this test file.