Journey to the First Release of `tml` - A Markdown to HTML Converter
Published: 2023-11-23 15:13:34

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](https://pypi.org/), 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:

```shell
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](https://twine.readthedocs.io/en/latest/), a utility for publishing Python packages on PyPI.

The command was simple:

```shell
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:

```shell
pip install tml
```

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

```shell
tml <path-to-file>
```

To specify an output directory:

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

The complete instructions are available on the [project's README](https://github.com/mnajibi/tml).

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!