From b2c1173a38204c4afb8a39656014a88027c63d42 Mon Sep 17 00:00:00 2001 From: Matt Kane Date: Thu, 7 Dec 2023 22:48:29 +0000 Subject: [PATCH] chore: update contribution guide (#106) --- CONTRIBUTING.md | 42 +++++++++++++++++++++++++++++++++--------- 1 file changed, 33 insertions(+), 9 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 823bd1c..32181a2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,8 +3,8 @@ :heart: We love contributions of new CDNs, bug fixes, and improvements to the code. -To add new domains or subdomains to an existing CDN, add them to `domains.json` -or `subdomains.json` respectively. +To add new domains, subdomains or paths to an existing CDN, add them to one or +more of the JSON files in `data`. To add a new CDN, add the following: @@ -14,20 +14,37 @@ To add a new CDN, add the following: that implements the `UrlGenerator` interface. - if the CDN should delegate remote source images to a different CDN where possible, implement `delegateUrl` and import it in `src/delegate.ts`. This is - likely to apply to all self-hosted image servers. See the `vercel` transformer + likely to apply to all self-hosted image servers. See the `ipx` transformer for an example. - a new test file in `src/transformers`. This should test all of the exported - API functions. + API functions, - at least one entry in `domains.json`, `subdomains.json` or `paths.json` to - detect the CDN. Do not include paths that are likely to cause false positives. - e.g. `/assets` is too generic, but `/_mycdn` is ok. + detect the CDN, unless it is not auto-detected. Do not include paths that are + likely to cause false positives. e.g. `/assets` is too generic, but `/_mycdn` + is ok. - add the new CDN to the types in `src/types.ts` - import the new source file in `src/transform.ts` and `src/parse.ts` - add a sample image to `examples.json` in the demo site. Run the site locally - to see that it works. -- ensure tests pass by installing Deno and running `deno test src --allow-net` + to see that it works. This step is important! This is used for the e2e tests + to ensure that the transformer works as expected, so it needs a real image to + work with. Ideally this should be a public sample image used in the CDN's own + docs, but if that is not available then any image hosted on the CDN will do. -### Image defaults +## Testing + +This project uses [Deno](https://deno.com/) for development, so there is no +install or build step. To run the tests you need to install Deno, then run: + +```sh +deno test src --allow-net +``` + +This will run all of the unit tests and e2e tests. + +The playground site is in `demo`. To run it locally, run `yarn install` then +`yarn dev` in the demo directory. + +## Image defaults When generating image URLs, we expect transformers to use the following defaults if supported, to ensure consistent behaviour across all CDNs: @@ -41,3 +58,10 @@ if supported, to ensure consistent behaviour across all CDNs: - No upscaling. The image should not be upscaled if it is smaller than the requested dimensions. Instead it should return the largest available size, but maintain the requested aspect ratio. + +## Publishing + +The module is published to both [deno.land](https://deno.land/x/unpic) and +[npm](https://www.npmjs.com/package/unpic), with the npm version generated using +[dnt](https://github.com/denoland/dnt). This is handled automatically by GitHub +Actions.