Repository Requirements

All products submitted to the GBTI network must:

  • Have an origin/repository on the gbti-network GitHub organization
    • Please contact an an administrator to have one assigned to you.
  • Include a .product folder with standardized documentation and assets
  • Use main as the default Git branch

.product Folder Structure

The .product folder must contain the following files and directories:

.product/
├── video.md
├── icon-256x256.png
├── icon-128x128.png
├── description.md
├── changelog.md
├── screenshots/
│   └── screenshot-[number].png
└── docs/
    ├── user/
    │   └── [user-docs].md
    └── dev/
        └── [dev-docs].md

File Standards and Requirements

video.md

Purpose:
Contains a link to the product demonstration video. This is optional, but highly encouraged.

Standards:

  • Must contain a single YouTube URL to the official product demonstration video
  • The URL should be on its own line without any additional formatting
  • Example format:
    https://www.youtube.com/watch?v=VIDEO_ID

icon-256x256.png and icon-128x128.png

Purpose:
Product icons at different resolutions for use in various contexts.

Standards:

  • Must be in PNG format
  • Must be exactly 256×256 pixels and 128×128 pixels respectively
  • Should be visually consistent with each other
  • Should clearly represent the product’s branding

banner-1544×500.png

Purpose:
This will be displayed at the top of the GBTI Network product page.

Standards:

  • Must be in PNG format
  • Must be exactly 1544×500 pixels
  • Should be visually consistent with each other
  • Should clearly represent the product’s branding

description.md

Purpose:
Comprehensive description of the product for marketing and documentation.

Standards:

  • Must be in Markdown format
  • Should begin with a level-2 heading (##) with the product name
  • Should include:
    • Brief overview (1–2 paragraphs)
    • A “We built this to:” section explaining the purpose
    • A bullet list of features
    • Optional: Setup instructions / Usage instructions.
  • Should be between 200–1500 words
  • Should not contain HTML markup

changelog.md

Purpose:
Documents version history and changes made to the product.

Standards:

  • Must be in Markdown format
  • Each version should be documented with:
    • Version number and release date as a level-2 heading (##)
    • Format: ## [Version] - [Month Day, Year]
    • Bullet points listing changes, fixes, and improvements
  • Versions should be listed in reverse chronological order (newest first)
  • Each entry should be concise but descriptive
  • Must include all public releases
  • Should categorize changes (e.g., “Bug fixes”, “New features”, “Improvements”)

Example:

## 1.2.5 - Mar 9, 2025

- Correcting issue with incorrect URL to associated 
- Bug fix with updates module & adding update test page. 

## 1.2.1 - Dec 1, 2024

- Maintenance work on HTML in comments.
- Incrementing 1.2.1 to test update workflow.

## 1.2.0 - Dec 1, 2024

- First public release. Let's go!

screenshots/ Directory

Purpose:
Contains screenshots showcasing the product’s interface and functionality.

Standards:

  • Must contain at least 1 screenshot (maximum recommended: 10)
  • Files must be named sequentially:
    • screenshot-1.png, screenshot-2.png, etc.
  • Format: PNG
  • Recommended resolution: 1280×800 pixels (or similar 16:10 ratio)
  • File size should be optimized (typically under 200KB per screenshot)

Screenshots should:

  • Showcase key features of the product
  • Be clear and professionally presented
  • Include captions in the WordPress plugin readme.txt file
  • Be current and reflect the latest version of the product

docs/ Directory

Purpose:
Contains comprehensive documentation for both users and developers of the product. If the product is small and does not require documentation, this can be skipped.

Structure:

  • docs/user/ — End-user documentation explaining how to use the product
  • docs/dev/ — Developer documentation for customization and extension

User Documentation (docs/user/)


Provides guidance for end users on how to use the product effectively.

  • Must be in Markdown format
  • Files should be named descriptively (e.g., about-the-product.md, getting-started.md)
  • Should begin with a Level-1 header (#) representing the title.

Developer Documentation (docs/dev/)

Provides technical documentation for developers who want to customize or extend the product.

  • Must be in Markdown format
  • Files should be named by technical focus (e.g., theme-customization.md, api-reference.md)
  • Should begin with a Level-1 header (#) representing the title.

Note: For small or single-purpose products, the docs/ directory may be minimal or omitted. For extensible or complex products, full user/ and dev/ documentation is expected.

Working with Git Repositories

All products must use main as the default branch. Below are Git CLI instructions for both new and existing repositories.

Creating a New Repository

git init
git checkout -b main
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/gbti-network/your-repo-name.git
git push -u origin mainCode language: JavaScript (javascript)

🔁 Replace your-repo-name with your actual repository name.

Updating an Existing Repository

git clone https://github.com/gbti-network/your-repo-name.git
cd your-repo-name
# Make your changes
git add .
git commit -m "Your commit message"
git push origin mainCode language: PHP (php)

Creating an Official GitHub Release

Once your product is ready for public distribution, you must create an official release on GitHub. This process packages your current codebase, assigns it a version tag, and makes it downloadable through the repository’s Releases tab.

Requirements Before Releasing

Before creating a release, ensure:

  • The main branch contains the latest production-ready code
  • The .product/ folder is up to date
  • The changelog.md file includes an entry for the version being released
  • The plugin or product files reflect the correct version number (e.g., in plugin.php and package.json)
  • All commits for this release have been pushed to GitHub

Steps to Create a Release on GitHub (Web Interface)

  1. Navigate to your repository on GitHub within the gbti-network organization
  2. Click on the “Releases” tab
  3. Click “Draft a new release”
  4. Under “Tag version”, enter a new tag (e.g., v1.0.0)
    • Make sure it matches the version listed in your plugin files and changelog.md
  5. Under “Target”, ensure main is selected
  6. Enter a release title (e.g., Version 1.0.0)
  7. In the description, paste the changelog section corresponding to this version
  8. Select “Publish release” to make it live

Tag Naming Format

  • ✅ 1.0.0
  • ❌ release-1.0.0, 1.0

Git Best Practices

  • Always work on the main branch unless directed otherwise
  • Use clear, descriptive commit messages
  • Keep the .product/ folder up to date in every commit
  • Use Pull Requests for collaboration and reviews when appropriate

Submission Process

  1. Ensure all required files are present and meet the documented standards
  2. Verify that the repository is correctly hosted under the gbti-network GitHub organization
  3. Submit the product for review through the designated submission channel
  4. Address any requested changes or improvements
  5. Once approved, the product will be published to the GBTI network

By following these guidelines, contributors help ensure that all GBTI network products meet a consistent level of quality, usability, and professionalism—resulting in better adoption and reduced support needs.