@talisdev/bibliographic-resource-parsers-lib 5.23.4

package/README.md

@@ -0,0 +1,102 @@
+# Bibliographic resource parsers lib
+
+Welcome to Bibliographic resource parsers lib! This guide will walk you through setting up the development environment and getting started with contributing to the project.
+
+## Contributing
+
+We follow the conventional commits specification for our PR titles. When creating a Pull Request, the title of the PR will be used as the commits will be squashed and merged in the main branch.
+
+Therefore, it is mandatory to use conventional commit messages in the title of your PR. To enforce this, we use a GitHub action that validates the PR title conforms to the Conventional Commits conventions.
+
+We use this standard to help us correctly version the project and generate changelogs automatically.
+
+For more information about conventional commits, you can refer to [Conventional Commits Specification](https://www.conventionalcommits.org/).
+
+## Setting Up the Development Environment
+
+### Prerequisites
+
+Before you begin, make sure you have the following installed:
+
+- nvm
+- Node.js - version is defined in `.nvmrc` file
+- Git
+
+## Getting Started
+
+```bash
+git clone git@github.com:talis/bibliographic-resource-parsers-lib.git
+cd bibliographic-resource-parsers-lib
+```
+
+You can run the following `nvm` command to install and use the required Node.js version:
+
+```bash
+nvm install && nvm use
+```
+
+### Install Dependencies
+
+```bash
+npm install
+```
+
+## Linting & Formatting
+
+Code standards and formatting are enforced using [ESLint](https://eslint.org/docs/latest/) and [Prettier](https://prettier.io/docs/en/).
+
+You can analyse your code for standards issues using:
+
+```bash
+npm run lint
+```
+
+You can reformat and apply automatic fixes by running:
+
+```bash
+npm run format
+```
+
+## Build library
+
+To build the library run:
+
+```bash
+npm run build
+```
+
+## Running/Writing Tests
+
+To run the tests, you can use the following command:
+
+```bash
+npm test
+```
+
+### Parser Tests
+Parser tests use HTML fixtures saved from real-world examples. These should be specified in the tests as URLs which will be mapped to fixtures and snapshots. 
+
+The general format of a parser test is as follows:
+
+```typescript
+const urls = [
+    'https://www.example.com',
+];
+
+test.each(urls)('should parse %s', async url => {
+    const fixture = await loadFixture(__dirname, url);
+    const resourceData = convertToResourceData(url, fixture);
+    
+    const result = yourParserUnderTest(resourceData);
+    
+    await expect(result).toMatchFileSnapshot(getSnapshotPath(__dirname, url));
+});
+```
+
+If no fixture exists for a real-world example, the test will fail and prompt you to save the fixture using the command `npm run save-fixture {url} {saveDirectory}`. This will save the HTML from the URL to the specified directory. Running the test again will use the saved fixture.
+
+The fixture should be run through the parser under test and compared against a snapshot of the expected output. If the snapshot does not exist, it will be created. If it mismatches the output, the test will fail and Vitest will prompt you to update the snapshot.
+
+
+
+