How to Contribute to the DigitalPlat FreeDomain Project: A Complete Developer Guide

You can contribute to the DigitalPlat FreeDomain project by forking the GitHub repository, modifying the open-source WHOIS server or frontend components, and submitting pull requests for bug fixes, new domain extensions, documentation improvements, or test coverage.

The DigitalPlat FreeDomain repository powers a free domain registration service through a lightweight WHOIS server and static frontend interface. While the backend API remains closed-source, the project actively welcomes community contributions to its Python WHOIS logic, HTML/Tailwind frontend, and user documentation. This guide covers the repository structure, coding standards, and specific file locations you need to start contributing effectively.

Understanding the FreeDomain Architecture

Before submitting code, familiarize yourself with the three primary open-source components. The project separates concerns between domain query handling, user interface presentation, and instructional content.

Core WHOIS Service

The minimal WHOIS server runs on port 43 and handles domain lookup queries. In opensource/whois_server/whois.py, the core logic processes incoming socket connections and returns formatted domain registration data. This Python module uses the logging library for diagnostics and follows PEP-8 conventions with 4-space indentation. The server operates independently from the closed-source backend API, making it an ideal entry point for network protocol improvements or new top-level domain (TLD) support.

Frontend Interface

User-facing pages reside in opensource/frontend/ and utilize Tailwind CSS for styling. The file opensource/frontend/domainreg.html contains the domain registration form where users select TLDs like .dpdns.org or .us.kg. These static HTML files communicate with the backend via HTTP/HTTPS requests, but all presentation layer code—including accessibility attributes and responsive design—is fully open for community enhancement.

Documentation and Policies

Project governance and user guides live in the repository root and documents/ directory. The README.md defines contribution policies and supported domain extensions, while documents/tutorial/index.md provides step-by-step user onboarding. The file opensource/readme.md specifically clarifies which backend components remain closed-source, helping contributors understand the boundary between open and proprietary code.

Setting Up Your Development Environment

Start your contribution by creating a personal fork and local workspace. The repository contains no complex build system, so setup requires only Git and a text editor.

1. Fork the repository on GitHub to create your own copy under your username.

2. Clone your fork locally and enter the project directory:

   git clone https://github.com/<your-username>/FreeDomain.git
   cd FreeDomain

3. Create a feature branch with a descriptive name indicating your change:

   git checkout -b feature/add-json-whois-output

Contribution Workflow and Guidelines

DigitalPlat FreeDomain follows standard GitHub workflows with specific style requirements for each technology stack. Maintain consistency with existing code patterns to ensure fast review cycles.

Code Style Standards

• Python: Follow PEP-8 strictly, use 4-space indentation, and implement logging rather than print statements for debug output in whois.py.
• HTML/CSS: Use Tailwind utility classes exclusively, maintain semantic markup structure, and avoid inline CSS in domainreg.html or related frontend files.
• Markdown: Structure documentation with consistent ATX heading levels (H1 for titles, H2 for sections) and fenced code blocks for all examples.

Commit and Pull Request Process

After making your changes, commit with a clear, imperative message describing the specific modification:

git commit -m "Add UTF-8 encoding fix to WHOIS response handler"

Push your branch to your fork and open a Pull Request against the upstream main branch. Include a description of the problem, your solution, and manual testing steps performed. While the repository currently lacks automated tests, mention any local verification you completed, such as testing the WHOIS server with telnet localhost 43.

Key Contribution Areas

New contributors can make immediate impact across four primary categories, ranging from simple HTML updates to Python protocol enhancements.

Extending WHOIS Domain Support

Add new TLDs to the service by modifying the domain parsing logic in opensource/whois_server/whois.py. The get_whois() function (or the main whois() entry point depending on implementation version) contains conditional blocks that return formatted strings for specific domain endings. Adding support requires updating both the Python logic and the frontend selection dropdown.

Improving the Registration UI

Enhance opensource/frontend/domainreg.html to improve user experience through better form validation, ARIA accessibility labels, or responsive layout adjustments. Since the frontend uses static HTML with Tailwind CSS, changes deploy immediately without compilation steps. Focus on WCAG guidelines by adding aria-label attributes to interactive elements like the domain selection dropdown.

Adding Automated Tests

The repository currently contains no test suite, creating an opportunity to establish the testing framework. Create a tests/ directory and add pytest files that mock socket connections to verify WHOIS responses. Testing the whois() function with various domain inputs ensures that new TLD additions do not break existing functionality.

Documentation Improvements

Expand documents/tutorial/index.md with clearer registration workflows, DNS configuration guides, or troubleshooting sections. Documentation contributions follow the same pull request process as code changes and help reduce support overhead for maintainers.

Code Examples for Common Contributions

These practical examples demonstrate how to implement typical contributions while following project conventions.

Adding a New TLD to the WHOIS Server

Modify opensource/whois_server/whois.py to handle additional domain extensions by extending the response generator:

# opensource/whois_server/whois.py

def get_whois(query: str) -> str:
    """Return a WHOIS response based on the domain queried."""
    # Existing logic for current TLDs...

    
    if query.endswith('.example'):
        return (
            "Domain Name: example\n"
            "Registrar: DigitalPlat FreeDomain\n"
            "Status: ACTIVE\n"
            "Created: 2024-01-01\n"
        )
    
    # Fallback to default response

    return "No data for this domain."

This modification takes effect when the server processes queries through the main whois() handler (lines 7-13 in the current implementation).

Updating the Registration Form HTML

Add the new TLD option to opensource/frontend/domainreg.html so users can select it during registration:

<!-- opensource/frontend/domainreg.html -->
<select name="domain" id="domainSelect" class="input-field" required>
  <option value=".dpdns.org">.dpdns.org</option>
  <option value=".us.kg">.us.kg</option>
  <option value=".qzz.io">.qzz.io</option>
  <option value=".xx.kg">.xx.kg</option>
  <!-- New TLD contribution -->
  <option value=".example">.example</option>
</select>

No backend API changes are required for this frontend update, as the WHOIS server handles the new TLD independently.

Writing Unit Tests for WHOIS Logic

Establish test coverage by creating tests/test_whois.py with mocked socket interactions:

# tests/test_whois.py

import pytest
from opensource.whois_server.whois import whois

def test_whois_example_tld():
    response = whois("mydomain.example")
    assert "Domain Name: example" in response
    assert "Status: ACTIVE" in response
    assert "Registrar: DigitalPlat FreeDomain" in response

Configure GitHub Actions to run pytest on pull requests, providing the project's first continuous integration safety net.

Summary

Contributing to DigitalPlat FreeDomain requires understanding the separation between the open-source frontend/WHOIS components and the closed-source backend API. Key takeaways for potential contributors include:

• Focus areas: Concentrate changes on whois.py for domain logic, domainreg.html for UI improvements, and documents/tutorial/index.md for guides.
• Style compliance: Use PEP-8 for Python, Tailwind classes for HTML, and semantic markdown for documentation.
• Testing gap: The repository currently lacks automated tests, making test contributions particularly valuable.
• Workflow: Fork, branch, commit with clear messages, and submit detailed pull requests against the main branch.

Frequently Asked Questions

Do I need access to the backend API to contribute to DigitalPlat FreeDomain?

No, the backend API is not fully open-sourced according to opensource/readme.md. All contributions work within the open-source boundaries: the Python WHOIS server (whois.py), static HTML frontend files, and documentation. The WHOIS server and frontend communicate with the backend through standard HTTP/HTTPS requests, so you can develop and test UI changes using the existing staging environment or mock data.

What coding standards should I follow when modifying whois.py?

Follow PEP-8 conventions with 4-space indentation and use the logging module for any diagnostic output rather than print statements. The WHOIS server implementation in opensource/whois_server/whois.py handles raw socket connections, so ensure your code includes proper error handling for network encoding issues, particularly UTF-8 transformations when processing domain queries on port 43.

Can I add support for new domain extensions (TLDs) to the project?

Yes, adding new TLDs is a common and welcomed contribution. You must update two files: extend the conditional logic in opensource/whois_server/whois.py (typically in the get_whois() function) to return proper WHOIS data for the new extension, and add the corresponding <option> element in opensource/frontend/domainreg.html so users can select the domain during registration. Both changes should be submitted in a single pull request with clear testing notes.

How do I test my changes to the WHOIS server locally?

Since the repository currently lacks automated tests, perform manual verification by running the WHOIS server locally and querying it via telnet localhost 43 or whois -h localhost example.dpdns.org. For a more robust contribution, consider adding a pytest suite in a new tests/ directory that mocks the socket connection and verifies the whois() function returns expected strings for various domain inputs, as this addresses a current gap in the project's continuous integration setup.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}