iptv-database/CONTRIBUTING.md

Contributing Guide

• Data Scheme
• Channel Logo Guidelines
• Project Structure
• Scripts
• Workflows

Data Scheme

channels

Field	Description	Required	Example
id	Unique channel ID derived from the name and country separated by dot. May only contain Latin letters, numbers and dot.	Required	AnhuiTV.cn
name	Official channel name in English or call sign. May include: a-z, 0-9, space, -, !, :, &, ., +, ', /, », #, %, °, $, @, ?.	Required	Anhui TV
alt_names	List of alternative channel names separated by ;. May contain any characters except , and ".	Optional	安徽卫视;AHTV
network	Network of which this channel is a part. May contain any characters except , and ".	Optional	Anhui
owners	List of channel owners separated by ;. May contain any characters except , and ".	Optional	China Central Television
country	Country code from which the channel is transmitted. A list of all supported countries and their codes can be found in data/countries.csv	Required	CN
subdivision	Code of the subdivision (e.g., provinces or states) from which the broadcast is transmitted. A list of all supported subdivisions and their codes can be found in data/subdivisions.csv.	Optional	CN-AH
city	The name of the city in English from which the channel is broadcast. May contain any characters except , and ".	Optional	Hefei
broadcast_area	List of codes describing the broadcasting area of the channel separated by ;. Any combination of r/<region_code>, c/<country_code>, s/<subdivision_code>.	Required	c/CN;r/ASIA
languages	List of languages in which the channel is broadcast separated by ;. A list of all supported languages and their codes can be found in data/languages.csv.	Required	zho;eng
categories	List of categories to which this channel belongs separated by ;. A list of all supported categories can be found in data/categories.csv.	Optional	animation;kids
is_nsfw	Indicates whether the channel broadcasts adult content (TRUE or FALSE).	Required	FALSE
launched	Launch date of the channel (YYYY-MM-DD).	Optional	2016-07-28
closed	Date on which the channel closed (YYYY-MM-DD).	Optional	2020-05-31
replaced_by	The ID of the channel that this channel was replaced by.	Optional	CCTV1.cn
website	Official website URL.	Optional	http://www.ahtv.cn/
logo	Logo URL. Only URL with HTTPS protocol are allowed. Supported image types: PNG, JPEG. Max size: 512x512 pixels. The link should not be geo-blocked.	Required	https://example.com/logo.png

categories

Field	Description	Required	Example
id	Category ID	Required	news
name	Category name	Required	News

languages

Field	Description	Required	Example
name	Official language name	Required	Croatian
code	ISO 639-3 code of the language	Required	hrv

countries

Field	Description	Required	Example
name	Official name of the country	Required	Canada
code	ISO 3166-1 alpha-2 code of the country	Required	CA
languages	List of official languages of the country separated by ;. A list of all supported languages can be found in data/languages.csv.	Required	eng;fra
flag	Country flag emoji	Required	🇨🇦

subdivisions

Field	Description	Required	Example
country	Country code of the division	Required	CA
name	Official subdivision name	Required	British Columbia
code	ISO 3166-2 code of the subdivision	Required	CA-BC

regions

Field	Description	Required	Example
name	Official name of the region	Required	Central Asia
code	Abbreviated designation for the region. May only contain Latin letters in upper case. The minimum length is 3 letters.	Required	CAS
countries	List of country codes in the region	Required	KG;KZ;TJ;TM;UZ

blocklist

List of channels blocked at the request of copyright holders.

Field	Description	Required	Example
channel	Channel ID	Required	AnimalPlanetAfrica.us
ref	Link to removal request or DMCA takedown notice	Required	https://example.com/issues/0000

Channel Logo Guidelines

Since finding a suitable logo for the channel is not always possible, this list contains only recommendations and should just help you in choosing a logo from several options.

1. If the channel logo has several versions, it is better to choose a color one.

   That way there is less chance of the logo blending in with the background.

   

2. If the logo has changed over time, use the latest version.

   

3. If the channel has several versions of the logo, it is better to use the one used on air.

   

4. If there is a transparent background around the logo is better to cut it.

   That way it's much easier to scale the logo later.

   

Project Structure

• .github/
  • ISSUE_TEMPLATE/: issue templates for the repository.
  • workflows: contains GitHub actions workflows.
  • CODE_OF_CONDUCT.md: rules you shouldn't break if you don't want to get banned.
• .readme/
  • preview.png: image displayed in the README.md.
• data/: contains all data.
• scripts/: contains all scripts used in the repository.
• tests/: contains tests to check the scripts.
• CONTRIBUTING.md: file you are currently reading.
• README.md: project description displayed on the home page.

Scripts

These scripts are created to automate routine processes in the repository and make it a bit easier to maintain.

For scripts to work, you must have Node.js installed on your computer.

To run scripts use the npm run <script-name> command.

• act:check: allows to run the check workflow locally. Depends on nektos/act.
• act:update: allows to run the update workflow locally. Depends on nektos/act.
• act:deploy: allows to run the deploy workflow locally. Depends on nektos/act.
• db:validate: checks the integrity of data.
• db:export: saves all data in JSON format to the /.api folder.
• db:update: triggers a data update using approved requests from issues.
• lint: сhecks the scripts for syntax errors.
• test: runs a test of all the scripts described above.

Workflows

To automate the run of the scripts described above, we use the GitHub Actions workflows.

Each workflow includes its own set of scripts that can be run either manually or in response to an event.

• check: runs the db:validate script when a new pull request appears, and blocks the merge if it detects an error in it.
• update: sequentially runs db:update and db:validate scripts and commits all the changes if successful.
• deploy: after each update of the master branch runs the script db:export and then publishes the resulting files to the iptv-org/api repository.