How onjin/mkchangelog works
Project Type and Purpose
• The project is a command-line utility written in Python for generating a changelog from git commits following the conventional commits standard.
• It supports generating changelogs using git tags for versioning—but, as per the additional instructions, it can also support alternative version providers (for example, month-based versions or other date-based schemes).
• The tool is configurable (using an .ini configuration file) and supports custom templates via Jinja2 with additional template filters via a plugin/hooks system.
Analyzing the File Structure – Key Components
• Directories like src/mkchangelog hold the main library code.
• app.py: Most likely the CLI entry point.
• commands/ directory: Contains different subcommands (generate, commit, bump, settings) that implement various functions.
• config.py, core.py, parser.py, providers.py, models.py: Manage configuration, core logic, parsing commits, and interfacing with version providers.
• templates/ directory: Contains built-in Jinja2 templates (markdown, rst, text) used for rendering changelog.
• hookspecs.py and .mkchangelog.d/hooks.py: Show that a hooks system is in place allowing extension via custom filters.
• Other directories include tests (unit tests for various components), docs (documentation), and configuration in CI/CD folders (.github).
• The .mkchangelog.d directory holds additional version-specific files (headers, footers, commit text files) that allow inclusion of extra commit messages for versions.
A. CLI Interface and Command Dispatcher:
• Entry-point (app.py) that parses command-line arguments.
• The dispatcher routes commands (generate, commit, bump, settings) to the corresponding module in the commands/ folder.
B. Core Engine:
• The core logic, located in core.py and lib.py, that orchestrates functionality:
• It retrieves configuration settings (from config.py).
• Calls the commit parser (parser.py) to process git log messages.
• Manages the grouping and sorting of commits based on conventional commits.
C. Version Provider Module:
• This component is responsible for determining the versions to include.
• Git Tag Version Provider: Processes annotated git tags (default behavior).
• Date-based/Monthly Version Provider: (your additional design option) which can generate version identifiers based on dates.
• These providers may be configurable through the .mkchangelog file.
D. Template Rendering Engine:
• Uses Jinja2 to render the final changelog output.
• The built-in templates are stored under src/mkchangelog/templates.
• Includes a custom filter system enabled via hooks (see .mkchangelog.d/hooks.py) that allows additional filters (e.g., fancylize, underline, regex_replace).
E. File System Integration:
• Handles files under .mkchangelog.d/versions for additional version-specific header, footer, and commit text file inputs.
F. Configuration and Hooks:
• The settings, loaded from configuration files (e.g., .mkchangelog, and .mkchangelog.d/hooks.py) feed into nearly all modules.
• The hooks system lets you extend functionality (like template filter registration and custom commit filtering).
Architectural Patterns and Relationships
• There is a clear separation of concerns: CLI parsing, core processing, version generation, and rendering are all in separate modules.
• The design leverages a plugin system (hooks) which is key for extensibility.
• Data flows from the configuration component to the version provider and parser, then to the rendering engine, and finally output to a file (default CHANGELOG.md) or stdout.
• The inclusion of additional static files (commits, headers, footers) enhances modularity and customization per version.
• Commands call the core engine.
• Core engine interacts with both version providers and parsing modules.
• The rendered output is directed to deployment/output (either file system or a Docker entry point).