DEV Community

Hitesh Sachdeva
Hitesh Sachdeva

Posted on

Releasing share-my-repo: A Journey from Local Code to PyPI

#release #programming #opensource #learning

Introduction

Over the past few weeks, I worked on share-my-repo, a CLI tool designed to package Git repositories into a format suitable for analysis by Large Language Models (LLMs). The goal was to create a user-friendly, configurable tool that could extract repository metadata, and generate structured file outputs.

Once the tool was ready, the next step was to release it so that others could easily install and use it via a package registry. This post walks through my entire release process, the challenges I faced, lessons learned, and the results of user testing.

Choosing a Release Tool and Package Registry

I decided to use Python’s standard packaging tools along with PyPI as the package registry. Specifically:

These tools are standard in the Python ecosystem and widely used for publishing Python packages.

Creating a Release

The release process involved several steps:

Updating Version

I updated the pyproject.toml to bump the version from 1.0.0 to 1.2.0.

Building the Package

I created a source distribution and a wheel using:

python -m build
Enter fullscreen mode Exit fullscreen mode

This Produced:

dist/share_my_repo-1.2.0.tar.gz
dist/share_my_repo-1.2.0-py3-none-any.whl
Enter fullscreen mode Exit fullscreen mode

Uploading to PyPI

I uploaded the distributions using twine:

python -m twine upload dist/*
Enter fullscreen mode Exit fullscreen mode

Tagging the Release in GitHub

After pushing my code, I created a Git tag for the release:

git tag v1.2.0
git push origin main --tags
Enter fullscreen mode Exit fullscreen mode

This made the release visible on GitHub under Releases.

Lessons Learned

  • pyproject.toml is powerful: Switching from setup.py to pyproject.toml made the build process cleaner and more modern.

  • User testing highlights documentation gaps: Even small missing instructions in README.md caused confusion for first-time users.

  • One "aha!" moment was realizing that setuptools_scm can auto-generate version numbers from Git tags, which makes managing releases much easier in the long run.

Changes Required for Package Format

To release share-my-repo successfully, I had to:

  1. Move from a setup.py file to a pyproject.toml configuration.
  2. Organize source code under a src folder to comply with best practices.
  3. Add [project.scripts] entries in pyproject.toml for CLI functionality.
  4. Ensure dependencies were correctly listed under [project.dependencies] and [project.optional-dependencies].

These changes were mostly structural and did not require altering the core functionality of the tool.

User Testing

I conducted a user testing session with a fellow classmate. Key observations:

  • They were able to install the package from PyPI without any issues.
  • Confusion arose when using optional flags like --preview and --use-gitignore because the README did not clearly explain the default behavior.
  • After observing them, I updated the README to include examples with common flag combinations.

This session was invaluable because it allowed me to fix documentation issues before sharing the package widely.

Installation & Usage

After release, users can install the package directly from PyPI release:

Install via PyPI 

pip install share-my-repo
Enter fullscreen mode Exit fullscreen mode

Install from Github

If you want to install the package directly from GitHub:

  1. Clone the repository:

For End Users

Clone and install the package:

# clone the repository 
git clone https://github.com/yourusername/share-my-repo.git
cd share-my-repo

# install dependencies
pip install .
Enter fullscreen mode Exit fullscreen mode

For Development / Contributors

Install in editable mode to make code changes without reinstalling:

# clone the repository 
git clone https://github.com/yourusername/share-my-repo.git
cd share-my-repo

# install dependencies
pip install -e .
Enter fullscreen mode Exit fullscreen mode

Usage 

share-my-repo [OPTIONS] [PATHS...]
Enter fullscreen mode Exit fullscreen mode

Some Examples

Process the current directory and print Markdown to console: 

share-my-repo .
Enter fullscreen mode Exit fullscreen mode

Process a repository and save output to a file: 

share-my-repo . --output repo_context.md
Enter fullscreen mode Exit fullscreen mode

Include only Python and JavaScript files: 

share-my-repo . --include "*.py,*.js"
Enter fullscreen mode Exit fullscreen mode

Output as JSON: 

share-my-repo . --format json --output repo.json
Enter fullscreen mode Exit fullscreen mode

Conclusion

Releasing share-my-repo taught me key lessons:

  • Versioning is crucial: Always increment versions to avoid PyPI upload errors.
  • Modern packaging works: pyproject.toml makes builds cleaner and easier to manage.
  • Clear documentation matters: User testing revealed gaps and helped improve the README.
  • Automation helps: setuptools_scm simplifies version management.
  • User perspective is important: Observing real users showed how to make CLI options more intuitive.

Overall, this experience improved my understanding of Python packaging, release workflows, and creating user-friendly documentation.

Top comments (0)