Hello fellow developers and curious minds,

Today, I want to share my journey of releasing tml, a command-line tool designed to convert .txt and .md files into .html format. This blog post will outline the process from choosing a release tool to user testing, aiming to provide a helpful guide for those looking to do the same.

Choosing a Release Tool and Package Registry

For tml, I chose to distribute the package using PyPI, the Python Package Index, which is the de facto package registry for Python projects. PyPI is a repository of software for the Python programming language that helps users find and install software developed and shared by the Python community.

The Release Process

The process began with organizing the project structure. Ensuring that the code was in a state that would be recognized by Python's packaging tools was key. This meant creating a src directory, adding an __init__.py file, and updating the import statements accordingly.

Next, I created a setup.py file at the root of the project. This script is crucial as it contains all the metadata about your package, such as the name, version, author, and dependencies.

With the setup.py in place, the next step was to build the distribution files. I used the following commands:

python setup.py sdist bdist_wheel

These commands create a source distribution and a wheel, respectively. After building the distributions, I uploaded them to PyPI using Twine, a utility for publishing Python packages on PyPI.

The command was simple:

twine upload dist/*

Learning and "Aha!" Moments

Throughout this process, I learned the importance of a well-organized codebase. One of my "aha!" moments was when I realized the significance of the __init__.py files. They may be empty, but they play an essential role in defining package structures.

I also learned about semantic versioning, which is a 3-part system for versioning software in the format of MAJOR.MINOR.PATCH. This was an "aha!" moment as I understood how it helps communicate the scope of changes in a release.

Alterations to Accommodate the Release

Adjusting the project to fit the packaging structure required moving files around, creating new directories, and ensuring the setup.py script accurately represented the project's dependencies and metadata. Thankfully, the alterations were minimal as my code was already modular.

User Testing Session

User testing was an enlightening experience. Watching someone interact with tml without any context exposed some assumptions I had made in my documentation. My tester got stuck on the installation process, as I had omitted the command to install tml from PyPI. After this session, I updated the README.md to clarify the installation and usage instructions.

Installation and Usage Post-Release

Users can now install tml using pip:

pip install tml

Once installed, you can convert files with the following command:

tml <path-to-file>

To specify an output directory:

tml <path-to-file> --output <path-to-output-directory>

The complete instructions are available on the project's README.

In conclusion, releasing tml was a journey filled with learning experiences. I hope that sharing my process will help demystify the release process for other developers. The project is now available for use and contribution, and I welcome any feedback to make tml even better.

Thank you for reading!