diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c9a5b3a3..df82caeb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,41 +1,26 @@ # Contributing Guide -### How to add a channel to the database or edit its description? - -1. Download the repository to your computer. The easiest way to do this is via [GitHub Desktop](https://desktop.github.com/). -2. Open [data/channels.csv](data/channels.csv) file in one of the spreadsheet editors (such as [Google Sheets](https://www.google.com/sheets/about/), [LibreOffice](https://www.libreoffice.org/discover/libreoffice/), ...). -3. Make the necessary changes and save the file. -4. Make a [pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) with all changes. This can also be done via [GitHub Desktop](https://desktop.github.com/). - -**IMPORTANT:** Since different programs process CSV files differently before publishing an edited file, please make sure that: - -- no extra columns (commas) were added to the file -- only [CRLF](https://developer.mozilla.org/en-US/docs/Glossary/CRLF) is used to indicate the end of a line -- no empty lines at the end of the file +- [Data Scheme](#data-scheme) +- [Channel Logo Guidelines](#channel-logo-guidelines) +- [Project Structure](#project-structure) +- [Scripts](#scripts) +- [Workflows](#workflows) ## Data Scheme -- [channels](#channels) -- [categories](#categories) -- [countries](#countries) -- [languages](#languages) -- [regions](#regions) -- [subdivisions](#subdivisions) -- [blocklist](#blocklist) - ### 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 | `安徽卫视` | +| 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](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](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/`, `c/`, `s/`. | Required | `c/CN;r/EUR` | +| broadcast_area | List of codes describing the broadcasting area of the channel separated by `;`. Any combination of `r/`, `c/`, `s/`. | 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](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](data/categories.csv). | Optional | `animation;kids` | | is_nsfw | Indicates whether the channel broadcasts adult content (`TRUE` or `FALSE`). | Required | `FALSE` | @@ -118,3 +103,44 @@ Since finding a suitable logo for the channel is not always possible, this list 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](https://docs.github.com/en/actions/quickstart) 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](https://nodejs.org/en) installed on your computer. + +To run scripts use the `npm run ` command. + +- `act:check`: allows to run the [check](https://github.com/iptv-org/iptv/blob/master/.github/workflows/check.yml) workflow locally. Depends on [nektos/act](https://github.com/nektos/act). +- `act:update`: allows to run the [update](https://github.com/iptv-org/iptv/blob/master/.github/workflows/update.yml) workflow locally. Depends on [nektos/act](https://github.com/nektos/act). +- `act:deploy`: allows to run the [deploy](https://github.com/iptv-org/iptv/blob/master/.github/workflows/deploy.yml) workflow locally. Depends on [nektos/act](https://github.com/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](https://docs.github.com/en/actions/using-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](https://github.com/iptv-org/database/branches) branch runs the script `db:export` and then publishes the resulting files to the [iptv-org/api](https://github.com/iptv-org/api) repository.