Skip to content

Commit 84bb78d

Browse files
atldaysatldays
committed
docs: update LICENSE, CONTRIBUTING, and README for clarity and completeness
1 parent 6ec446d commit 84bb78d

4 files changed

Lines changed: 134 additions & 35 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 112 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,119 @@
11
# Contributing
22

3-
## Requirements
3+
Thanks for taking the time to improve `srcset-kit`.
44

5-
- Node.js 22 or newer for local development.
5+
This package is intentionally small: it parses, validates, and serializes HTML
6+
`srcset` values without runtime dependencies. Contributions are most helpful
7+
when they keep that focus clear.
8+
9+
## Getting Started
10+
11+
Requirements:
12+
13+
- Node.js 22 or newer;
614
- pnpm 10 or newer.
715

8-
## Local checks
16+
Install dependencies:
917

1018
```sh
1119
pnpm install
20+
```
21+
22+
Run the full local check:
23+
24+
```sh
25+
pnpm run verify
26+
```
27+
28+
`verify` is the same kind of check expected before a release. It runs formatting
29+
checks, linting, type checking, tests, the production build, and package export
30+
validation.
31+
32+
## Useful Commands
33+
34+
Use the full check before opening a pull request:
35+
36+
```sh
1237
pnpm run verify
1338
```
1439

1540
Use focused commands while developing:
1641

1742
```sh
1843
pnpm run test
19-
pnpm run build
44+
pnpm run test:watch
2045
pnpm run typecheck
46+
pnpm run lint
2147
pnpm run format
48+
pnpm run format:check
49+
pnpm run build
50+
pnpm run pack:check
51+
```
52+
53+
## Project Shape
54+
55+
The main files are:
56+
57+
- `src/parse.ts` for the public parser entrypoint;
58+
- `src/parser.ts` for internal tokenization;
59+
- `src/validator.ts` for validation rules and issue codes;
60+
- `src/stringify.ts` for serialization;
61+
- `src/types.ts` for public types;
62+
- `src/errors.ts` for package-specific errors;
63+
- `tests/index.test.ts` for behavior coverage;
64+
- `README.md` for public examples and user-facing API docs.
65+
66+
## Public API Changes
67+
68+
Keep the public surface small and intentional. The runtime API is:
69+
70+
- `parse`;
71+
- `validate`;
72+
- `stringify`.
73+
74+
When changing public behavior, update these together:
75+
76+
- exported types in `src/types.ts`;
77+
- exports in `src/index.ts`;
78+
- user-facing examples in `README.md`;
79+
- tests in `tests/index.test.ts`.
80+
81+
Please avoid adding dependencies unless the benefit is clearly worth the extra
82+
package weight.
83+
84+
## Testing Guidelines
85+
86+
Add focused tests for the behavior you change.
87+
88+
Parser changes should cover cases like:
89+
90+
- commas inside URLs;
91+
- `data:` URLs;
92+
- relative and absolute URLs;
93+
- query strings and fragments;
94+
- whitespace and newlines;
95+
- tolerant parsing of invalid descriptor sets.
96+
97+
Validator changes should assert stable issue codes, not only messages.
98+
99+
Stringifier changes should cover normalized output and round trips with
100+
`parse()` when possible.
101+
102+
If object validation changes, add candidate-array tests in addition to string
103+
input tests.
104+
105+
## Documentation Guidelines
106+
107+
Keep README examples short, copyable, and aligned with the actual API.
108+
109+
If a feature affects how users call `parse`, `validate`, or `stringify`, update
110+
the README in the same pull request. Use the repository's TypeScript formatting
111+
style in examples, including compact object and import braces:
112+
113+
```ts
114+
import {parse, validate} from "srcset-kit";
115+
116+
validate([{url: "image.png", density: 1}]);
22117
```
23118

24119
## Commits
@@ -28,12 +123,13 @@ This repository uses Conventional Commits. Examples:
28123
```text
29124
feat: add srcset parser
30125
fix: keep descriptor whitespace valid
126+
docs: improve validation examples
31127
chore(release): merge main back into develop
32128
```
33129

34130
Husky runs `commitlint` for commit messages.
35131

36-
## Branch flow
132+
## Branch Flow
37133

38134
The repository follows a GitFlow-like process without requiring the GitFlow CLI:
39135

@@ -43,7 +139,7 @@ The repository follows a GitFlow-like process without requiring the GitFlow CLI:
43139
- after the release pull request is merged, GitHub Release and npm publishing run automatically;
44140
- merge `main` back into `develop` after every release so `develop` receives the version, changelog, and lockfile updates.
45141

46-
When a merge commit is created manually, keep the merge message conventional, for example:
142+
When a merge commit is created manually, keep the merge message conventional:
47143

48144
```text
49145
chore(release): merge main back into develop
@@ -58,3 +154,13 @@ Husky hooks are installed by `pnpm install`.
58154
- `commit-msg` validates Conventional Commits.
59155
- `pre-push` runs tests and the build.
60156

157+
## Release Readiness
158+
159+
Before a release, make sure:
160+
161+
- `pnpm run verify` passes;
162+
- README examples match the exported API;
163+
- public type changes are covered by tests;
164+
- `CHANGELOG.md` is ready for the release flow;
165+
- package metadata in `package.json` still matches the published package;
166+
- the license file remains `LICENSE.md`.

‎LICENSE‎

Lines changed: 0 additions & 22 deletions
This file was deleted.

‎LICENSE.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# MIT License
2+
3+
Copyright (c): Anjey Tsibylskij
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
6+
7+
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
8+
9+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

‎README.md‎

Lines changed: 13 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,10 @@
11
# srcset-kit
22

3+
[![npm version](https://img.shields.io/npm/v/srcset-kit.svg?logo=npm&style=for-the-badge)](https://www.npmjs.com/package/srcset-kit)
4+
[![npm downloads](https://img.shields.io/npm/dm/srcset-kit.svg?style=for-the-badge&color=blue)](https://www.npmjs.com/package/srcset-kit)
5+
[![CI](https://img.shields.io/github/actions/workflow/status/atldays/srcset-kit/ci.yml?style=for-the-badge)](https://github.com/atldays/srcset-kit/actions/workflows/ci.yml)
6+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](LICENSE.md)
7+
38
Small, dependency-free tools for parsing, validating, and serializing HTML
49
`srcset` values.
510

@@ -40,15 +45,16 @@ yarn add srcset-kit
4045
import {parse, stringify, validate} from "srcset-kit";
4146

4247
const candidates = parse("image.png 1x, image@2x.png 2x");
48+
// [
49+
// {url: "image.png", density: 1},
50+
// {url: "image@2x.png", density: 2},
51+
// ]
4352

44-
const result = validate(candidates, {
45-
descriptor: "density",
46-
});
53+
const result = validate("image.png 1x, image@2x.png 2x");
54+
// result.valid === true
4755

48-
if (result.valid) {
49-
stringify(result.candidates);
50-
// "image.png 1x, image@2x.png 2x"
51-
}
56+
const srcset = stringify(candidates);
57+
// "image.png 1x, image@2x.png 2x"
5258
```
5359

5460
## Parse

0 commit comments

Comments
 (0)