# How to Contribute Changes to the Free-TV/IPTV Repository Using Pull Requests > Learn to contribute to the Free-TV/IPTV repository by editing markdown files, validating changes, and submitting pull requests. Enhance your favorite channels today! - Repository: [Free TV/IPTV](https://github.com/Free-TV/IPTV) - Tags: how-to-guide - Published: 2026-06-26 --- **Contributing to Free-TV/IPTV requires editing country-specific markdown files in `lists/*.md`, validating changes locally with [`make_playlist.py`](https://github.com/Free-TV/IPTV/blob/main/make_playlist.py), and submitting a pull request that never modifies the auto-generated `playlist.m3u8` file.** The Free-TV/IPTV project maintains a collaborative database of free television streams through a streamlined, data-driven architecture. When you contribute changes to the Free-TV/IPTV repository using pull requests, you modify human-readable markdown tables that the Python generator converts into the final playlist. This workflow keeps the source of truth clean while ensuring automated M3U8 generation remains consistent across all contributions. ## Understanding the Repository Architecture The repository separates content metadata from generated output through three core components: - **`lists/*.md`** – Country-specific markdown files containing channel tables (e.g., [`lists/usa.md`](https://github.com/Free-TV/IPTV/blob/main/lists/usa.md)) - **[`make_playlist.py`](https://github.com/Free-TV/IPTV/blob/main/make_playlist.py)** – Python script that parses markdown sources and generates `playlist.m3u8` - **`playlist.m3u8`** – Auto-generated master playlist file that must never be edited manually This architecture ensures that all **channel metadata** lives in version-controlled markdown tables while the build process handles playlist compilation. By restricting contributions to the `lists/` directory, the project avoids merge conflicts in the large generated file and maintains rapid review cycles. ## Step-by-Step Guide to Submitting a Pull Request ### Fork and Clone the Repository Begin by creating your own copy of the repository and cloning it locally: ```bash git clone https://github.com/YOUR_USERNAME/IPTV.git cd IPTV ``` Replace `YOUR_USERNAME` with your actual GitHub username to target your forked copy. ### Create a Feature Branch Isolate your changes in a dedicated branch following the naming convention `add-new-channel-`: ```bash git checkout -b add-new-channel-usa ``` This keeps your main branch clean and allows maintainers to identify the purpose of your contribution quickly. ### Edit the Markdown Source Files Open the relevant country file in `lists/` (e.g., [`lists/usa.md`](https://github.com/Free-TV/IPTV/blob/main/lists/usa.md)) and add a new row to the channel table using the established format: ```markdown | 13 | MyFreeTV Ⓨ | [>](https://www.youtube.com/c/MyFreeTV/live) | | MyFreeTV.us | ``` Use the `[>]` marker before working stream URLs and `[x]()` for unavailable streams. Include the appropriate icons: **Ⓖ** for GeoIP-blocked streams, **Ⓨ** for YouTube sources, and **Ⓢ** for streams requiring specific user agents or headers. ### Validate Your Changes Locally Run the generator script to verify your markdown syntax produces valid playlist entries: ```bash python3 make_playlist.py ``` This command rewrites `playlist.m3u8` based on your updated markdown source. Do not commit the generated file; the project's policy requires regeneration during the build process to ensure consistency. ### Commit and Push to Your Fork Stage your markdown changes and commit with a descriptive message: ```bash git add lists/usa.md git commit -m "Add MyFreeTV channel for USA" git push origin add-new-channel-usa ``` Always verify that only `.md` files appear in your staging area before committing. ### Open the Pull Request Navigate to your fork on GitHub and click **Compare & pull request**. Fill the PR template completely by explaining why the channel qualifies as free-to-air, providing the logo URL, and confirming that the stream works in your region. The README explicitly states that only markdown files should be modified; ensure your diff contains no changes to `playlist.m3u8` or other generated assets. ## Critical Contribution Rules to Follow Adhering to these constraints ensures your pull request gets merged quickly: - **Never edit `playlist.m3u8`** – This file is auto-generated and will be overwritten by the build pipeline. - **Only modify `.md` files** – All channel data must reside in the `lists/` directory to maintain the data-driven workflow. - **Use proper table formatting** – Maintain the pipe-delimited structure with correct markers (`[>]`, `[x]()`) and icon annotations. - **Confirm stream availability** – Test that the URL resolves before submitting, as maintainers will verify functionality during review. ## Summary - Contribute changes to the Free-TV/IPTV repository by editing markdown files in `lists/*.md`, never the generated `playlist.m3u8`. - Validate your edits locally using `python3 make_playlist.py` before committing. - Use `[>]` for working streams, `[x]()` for broken ones, and include **Ⓖ**, **Ⓨ**, or **Ⓢ** icons where applicable. - Submit pull requests with descriptive branch names (e.g., `add-new-channel-usa`) and complete the PR template with licensing and verification details. ## Frequently Asked Questions ### Can I edit the playlist.m3u8 file directly? No. The `playlist.m3u8` file is auto-generated by [`make_playlist.py`](https://github.com/Free-TV/IPTV/blob/main/make_playlist.py) and must not be modified manually. Editing this file directly creates merge conflicts and violates the repository's data-driven architecture. Always edit the source markdown files in `lists/` instead. ### What do the icons Ⓖ, Ⓨ, and Ⓢ mean in the channel lists? These icons indicate stream characteristics: **Ⓖ** marks GeoIP-blocked streams (specify working countries in your PR description), **Ⓨ** identifies YouTube sources, and **Ⓢ** denotes streams requiring specific user agents or headers. Include these in the channel name column when applicable. ### How do I mark a stream as broken or unavailable? Use the `[x]()` marker in place of `[>]` before the URL in the markdown table. This signals to the generator that the stream is currently offline while preserving the metadata for future reactivation. Do not delete the entire row unless the channel has permanently ceased broadcasting. ### Why does my pull request need to include a logo URL? The project maintains a consistent visual standard by hosting channel logos through image URLs (typically Imgur). The logo appears in the generated playlist and web interfaces. Your PR description must include a working logo URL to ensure the channel displays correctly after merge.