From 7c15e2183bbb39122aa9ff3fb79ccac92f75c9ea Mon Sep 17 00:00:00 2001 From: S4NKALP Date: Sat, 13 Dec 2025 21:42:33 +0545 Subject: [PATCH] refactor(docs): Overhaul README for improved clarity and quick start The `README.md` has undergone a significant rewrite and restructuring to enhance readability, streamline the onboarding process, and better communicate the value proposition of DevGen. This includes a new introduction, a consolidated "Why DevGen?" section, simplified quick start guides, and a dedicated feature deep dive. * **Enhancements & Refinements** * **Improved Introduction**: Added a concise tagline and refined the introductory paragraph, positioning DevGen as an AI co-pilot for Git and project management. * **Streamlined Feature Presentation**: Replaced the previous feature list with a "Why DevGen?" section, highlighting key benefits such as AI Brain (multi-provider support), battle-tested compliance (Conventional Commits, Semantic Versioning), lightning-fast performance, and zero-friction setup. * **Simplified Quick Start**: Refined the initial setup and commit generation steps for a quicker onboarding experience. * **Enhanced Feature Deep Dive**: Introduced a dedicated section to provide detailed usage examples for AI-powered commits, changelogs, release notes, gitignore, and license generation. * **Improved Installation Instructions**: Emphasized `pipx` and `uv` as recommended installation methods for isolated and fast CLI management. * **Concise Configuration Table**: Replaced verbose configuration details with a clear markdown table for easier reference. * **Updated PyPI Link**: Corrected the PyPI link to `devgen-cli`. * **Minor Visual Updates**: Refined badge presentation and added a centered footer with author attribution. * **Refactoring** * **Major Content Restructuring**: Completely reordered and rewrote large sections, removing redundant information and consolidating related content to improve overall flow and conciseness. * **Removed Command Reference**: Integrated command examples directly into relevant usage sections, eliminating a separate, lengthy command reference. * **Removed Redundant Sections**: Consolidated information previously found in "Use Cases" and "Requirements" into other sections, streamlining the document. --- README.md | 266 +++++++++++++----------------------------------------- 1 file changed, 61 insertions(+), 205 deletions(-) diff --git a/README.md b/README.md index 7207c58..827f05f 100644 --- a/README.md +++ b/README.md @@ -1,263 +1,119 @@ # DevGen
+ +> **Your AI Co-Pilot for Git & Project Management.** +> Stop wasting time on repetitive tasks. Automate your commits, changelogs, and project essentials with a single CLI. +> > PyPI didn't allow the original name, so you'll find it as **devgen-cli** on PyPI -PyPI +PyPI Python License
-**DevGen** is an AI-powered developer toolkit that automates common Git and project management tasks. Generate semantic commit messages, changelogs, release notes, `.gitignore` files, and licenses all from a single unified CLI. +--- -## ✨ Features +**DevGen** isn't just another CLI toolβ€”it's your development workflow on steroids. By leveraging state-of-the-art AI models, DevGen turns tedious manual tasks into one-click magic. From semantic commit messages to comprehensive release notes, DevGen handles the boring stuff so you can focus on building. -- πŸš€ **AI-Powered Commit Messages** - Automatically generate semantic commit messages from your staged changes using AI -- πŸ“ **Changelog Generation** - Create changelogs from git history using conventional commits -- πŸš€ **Release Notes** - Generate clean, emoji-enhanced release notes for your releases -- πŸ™ˆ **Gitignore Templates** - Generate `.gitignore` files from GitHub's official templates -- πŸ“„ **License Generation** - Quickly generate open source licenses with interactive setup -- βš™οΈ **Multi-Provider AI Support** - Works with Gemini, OpenAI, Anthropic, HuggingFace, and OpenRouter +## ⚑ Why DevGen? + +- **🧠 AI Brain**: Semantic commit messages powered by Gemini, OpenAI, Claude, HuggingFace, and OpenRouter. It reads your diffs and understands your code. +- **πŸš€ Battle Tested**: Generates **Conventional Commits** and **Semantic Versioning** compliant changelogs that actually make sense. +- **⚑ Lightning Fast**: Smart caching and async operations mean you never wait longer than necessary. +- **Project Essentials**: Quickly add `.gitignore` and license files to your existing projects. Access cached templates instantly, even without internet. +- **πŸ› οΈ Zero Friction**: Interactive setup gets you running in seconds. ## πŸ“¦ Installation -```bash -# Stable release from PyPI -pip install devgen-cli +Get started in seconds. -# Using pipx (recommended for isolated CLI) +```bash +# Recommended: Install via pipx for an isolated environment pipx install devgen-cli -# Using uv (fast Python package manager) +# Or use uv for blazing speed uv tool install devgen-cli + +# Standard pip install +pip install devgen-cli ``` ## πŸš€ Quick Start -### 1. Initial Setup - -Configure your AI provider and API key: +**1. Initialize & Configure** +Tell DevGen which AI provider to use. ```bash devgen setup config ``` -This will create a configuration file at `~/.devgen.yaml` with your preferred AI provider, model, and API key. - -### 2. Generate Commit Messages - -Stage your changes and let DevGen generate semantic commit messages: +**2. Stage & Commit** +Stage your files and let AI write the message. ```bash -# Dry run to preview commit messages +git add . +devgen commit run +``` + +*Boom. Done.* + +## πŸ’‘ Feature Deep Dive + +### πŸ€– AI-Powered Commits +Stop writing "fix bug" or "wip". DevGen analyzes your staged changes, groups them by component, and generates meaningful, semantic commit messages. + +```bash +# Preview what DevGen will generate devgen commit run --dry-run -# Actually commit with AI-generated messages -devgen commit run - -# Commit and automatically push +# Commit and push in one go devgen commit run --push - -# Force regeneration of commit messages -devgen commit run --force-rebuild ``` -**How it works:** - -- DevGen detects all staged and unstaged changes -- Groups files by directory -- Generates semantic commit messages for each group using AI -- Follows [Conventional Commits](https://www.conventionalcommits.org/) format - -**Additional commit commands:** +### πŸ“ Changelogs & Release Notes +Turn your git history into beautiful, readable documentation. ```bash -# View cached commit messages -devgen commit list-cached - -# Clear the commit cache -devgen commit clear-cache - -# Check what files are staged -devgen commit validate -``` - -### 3. Generate Changelogs - -Create changelogs from your git history: - -```bash -# Generate changelog from last tag to HEAD +# Generate a changelog from the last tag devgen changelog generate -# Generate from a specific reference -devgen changelog generate --from v1.0.0 - -# Output to a custom file -devgen changelog generate --output CHANGES.md +# Create release notes for v2.0.0 +devgen release notes --version 2.0.0 ``` -The changelog follows Semantic Release conventions, categorizing commits into: - -- **BREAKING CHANGES** -- **Features** -- **Bug Fixes** -- **Documentation** -- **Other Changes** - -### 4. Generate Release Notes - -Create release notes for your releases: +### πŸ›‘οΈ Essential Files +Don't waste time searching for templates. Generate the essential files for your project instantly. ```bash -# Generate release notes -devgen release notes --version 1.4.0 - -# Custom output file -devgen release notes --version 1.4.0 --output RELEASE.md - -# From a specific reference -devgen release notes --version 1.4.0 --from v1.3.0 -``` - -### 5. Generate .gitignore Files - -Create `.gitignore` files from GitHub templates: - -```bash -# Interactive mode (search and select templates) +# Interactive search for gitignore templates devgen gitignore generate -# Specify templates directly -devgen gitignore generate Python Node Docker - -# List available templates -devgen gitignore list - -# Use cached templates (offline mode) -devgen gitignore generate --offline Python -``` - -**Options:** - -- `--append` / `--overwrite` - Append to or overwrite existing `.gitignore` -- `--output` - Specify output file path (default: `.gitignore`) -- `--offline` - Use only cached templates - -### 6. Generate Licenses - -Generate open source licenses interactively: - -```bash +# Generate a license interactively devgen license generate ``` -This will: - -1. Show available licenses (MIT, Apache-2.0, GPL-3.0, etc.) -2. Prompt for author name -3. Prompt for year (defaults to current year) -4. Generate the license file - -**Available licenses:** - -- MIT -- Apache-2.0 -- GPL-2.0, GPL-3.0 -- LGPL-2.1 -- AGPL-3.0 -- BSD-2-Clause, BSD-3-Clause -- MPL-2.0 -- EPL-2.0 -- BSL-1.0 -- CC0-1.0 -- Unlicense - ## βš™οΈ Configuration -Configuration is stored in `~/.devgen.yaml`. You can edit it manually or use the interactive setup: +Your settings live in `~/.devgen.yaml`. You can tweak your AI provider, model, and preferences there. -```bash -devgen setup config -``` - -**Configuration options:** - -- `provider` - AI provider: `gemini`, `openai`, `anthropic`, `huggingface`, or `openrouter` -- `model` - Model name (e.g., `gemini-2.5-flash`, `gpt-4`, `claude-3-opus`) -- `api_key` - Your API key -- `emoji` - Enable/disable emojis in commit messages (default: `true`) - -## πŸ“‹ Command Reference - -### Commit Commands - -```bash -devgen commit run [--dry-run] [--push] [--debug] [--force-rebuild] -devgen commit validate -devgen commit list-cached -devgen commit clear-cache -``` - -### Changelog Commands - -```bash -devgen changelog generate [--output FILE] [--from REF] -``` - -### Release Commands - -```bash -devgen release notes [--version VERSION] [--output FILE] [--from REF] -``` - -### Gitignore Commands - -```bash -devgen gitignore generate [TEMPLATES...] [--output FILE] [--append/--overwrite] [--offline] -devgen gitignore list [--cached] -``` - -### License Commands - -```bash -devgen license generate [--output FILE] -``` - -### Setup Commands - -```bash -devgen setup config -``` - -## 🎯 Use Cases - -- **Automated Commit Workflow**: Let AI analyze your changes and generate meaningful commit messages -- **Release Preparation**: Automatically generate changelogs and release notes from git history -- **Project Setup**: Quickly add `.gitignore` and license files to new projects -- **CI/CD Integration**: Use in scripts to automate documentation generation - -## πŸ”§ Requirements - -- Python 3.10 or higher -- Git repository (for commit/changelog/release features) -- API key for your chosen AI provider - -## πŸ“ License - -This project is licensed under the GPL-3.0-or-later License - see the [LICENSE](LICENSE) file for details. +| Option | Description | +|:---|:---| +| `provider` | `gemini`, `openai`, `anthropic`, `huggingface`, `openrouter` | +| `model` | Specific model name (e.g., `gemini-2.5-flash`, `gpt-4o`) | +| `emoji` | Enable/disable gitmojis in commits (`true`/`false`) | ## 🀝 Contributing -Contributions are welcome! Please feel free to submit a Pull Request. +We love contributions! Found a bug? Want a new feature? Open an issue or submit a PR. -## πŸ“š Links +## πŸ“ License -- **Homepage**: [https://github.com/S4NKALP/devgen](https://github.com/S4NKALP/devgen) -- **PyPI**: [https://pypi.org/project/devgen](https://pypi.org/project/devgen0cli) +Proudly open source under the [GPL-3.0-or-later](LICENSE) License. -## πŸ™ Acknowledgments +--- -- Uses GitHub's official [gitignore templates](https://github.com/github/gitignore) -- Follows [Conventional Commits](https://www.conventionalcommits.org/) specification +
+Made with ❀️ by Sankalp +