From f53ae439db615a003a8e4ee2baad5875ac56911e Mon Sep 17 00:00:00 2001
From: Aleksandr Statciuk <github@oiya.xyz>
Date: Fri, 18 Nov 2022 08:14:18 +0300
Subject: [PATCH] Create CONTRIBUTING.md

---
 CONTRIBUTING.md | 123 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 123 insertions(+)
 create mode 100644 CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 00000000..0de3ca66
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,123 @@
+# Contributing Guide
+
+### How do I add a program guide for the channel?
+
+First, open the [/sites](/sites) folder and select the source that you know has the guide for the channel you want.
+
+Then in the selected folder open the file `*.channels.xml` and add to it:
+
+```xml
+<channel lang="LANGUAGE_CODE" xmltv_id="CHANNEL_ID" site_id="SITE_ID">CHANNEL_NAME</channel>
+```
+
+| Attribute     | Description                                                                                                                                                        | Example     |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |
+| LANGUAGE_CODE | Language of the guide ([ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) code).                                                                   | `en`        |
+| CHANNEL_ID    | Channel ID from [iptv-org/database](https://github.com/iptv-org/database). A complete list of supported channels can also be found at https://iptv-org.github.io/. | `BBCOne.uk` |
+| SITE_ID       | Unique ID of the channel used in the source.                                                                                                                       | `bbc1`      |
+| CHANNEL_NAME  | Name of the channel used in the source.                                                                                                                            | `BBC 1`     |
+
+After that just commit all changes and send a pull request.
+
+### How to add a new source to the repository?
+
+To do this, you must create a new folder in the [/sites](/sites) with at least 3 files:
+
+<details>
+<summary>example.com.config.js</summary>
+<br>
+
+This file describes what kind of request we need to send to get the guide for a particular channel on a certain date. It also describes how to parse the response.
+
+```js
+module.exports = {
+	site: 'example.com',
+	url: function ({ channel, date }) {
+		return `https://example.com/api/${channel.site_id}/${date.format('YYYY-MM-DD')}`
+	},
+	parser: function ({ content }) {
+		return JSON.parse(content)
+	}
+}
+```
+
+More detailed instructions for this file can be found here: https://github.com/freearhey/epg-grabber#site-config
+
+</details>
+
+<details>
+<summary>example.com.test.js</summary>
+<br>
+
+With this file we can test the previously created config and make sure it works as you expect.
+
+```js
+const { url, parser } = require('./example.com.config.js')
+const dayjs = require('dayjs')
+const utc = require('dayjs/plugin/utc')
+dayjs.extend(utc)
+
+const date = dayjs.utc('2022-11-18', 'YYYY-MM-DD').startOf('d')
+const channel = { site_id: 'bbc1', xmltv_id: 'BBCOne.uk', lang: 'en' }
+
+it('can generate valid url', () => {
+	expect(url({ channel, date })).toBe('https://example.com/api/bbc1/2022-11-18')
+})
+
+it('can parse response', () => {
+	const content = `[{"start":"2022-11-18T01:30:00.000Z","stop":"2022-11-18T02:00:00.000Z","title":"Program 1"}]`
+	const results = parser({ content })
+
+	expect(results).toMatchObject([
+		{
+			start: '2022-11-18T01:30:00.000Z',
+			stop: '2022-11-18T02:00:00.000Z',
+			title: 'Program 1'
+		}
+	])
+})
+
+it('can handle empty guide', () => {
+	const results = parser({ content: '' })
+
+	expect(results).toMatchObject([])
+})
+```
+
+To run the tests you can use the following command:
+
+```sh
+npm test -- example.com
+```
+
+Detailed documentation for the tests can be found here: https://jestjs.io/docs/using-matchers
+
+</details>
+
+<details>
+<summary>example.com.channels.xml</summary>
+<br>
+
+This file contains a list of channels available at the source.
+
+```xml
+<?xml version="1.0" encoding="UTF-8" ?>
+<site site="example.com">
+ <channels>
+   <channel lang="en" xmltv_id="BBCOne.uk" site_id="bbc1">BBC 1</channel>
+ </channels>
+</site>
+```
+
+</details>
+<br>
+
+After creating all the files we can make sure that the guide loads correctly and has no errors using the command:
+
+```sh
+npx epg-grabber --config=sites/example.com/example.com.config.js --channels=sites/example.com/example.com.channels.xml --output=guide.xml --days=2
+```
+
+If the download is successful, the `guide.xml` file with the ready to use program should appear in the root directory.
+
+After that, all that remains is to commit all the changes and send a pull request.