Skip to content

Commit dadeff2

Browse files
YagoBorbaYagoBorba
authored
Merge pull request #19 from YagoBorba/docs/initial-project-documentation
Docs/initial project documentation
2 parents 0db8edb + 4084b87 commit dadeff2

7 files changed

Lines changed: 349 additions & 55 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
2+
# Contributing to StackCode
3+
4+
First off, thank you for considering contributing! It's people like you that make the open-source community such an amazing place. We welcome any contribution, from fixing a typo to implementing a whole new feature.
5+
6+
## Table of Contents
7+
8+
- [Code of Conduct](#code-of-conduct)
9+
- [How Can I Contribute?](#how-can-i-contribute)
10+
- [Development Setup](#development-setup)
11+
- [Git Workflow and Pull Requests](#git-workflow-and-pull-requests)
12+
- [Coding Style and Principles](#coding-style-and-principles)
13+
- [Commit Message Guidelines](#commit-message-guidelines)
14+
- [Testing](#testing)
15+
16+
## Code of Conduct
17+
18+
This project is governed by our [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.
19+
20+
## How Can I Contribute?
21+
22+
### Reporting Bugs
23+
If you find a bug, please check the [Issues](https://github.com/YagoBorba/StackCode/issues) to see if it has already been reported. If not, open a new one with a clear title, description, and steps to reproduce.
24+
25+
### Suggesting Enhancements
26+
Have an idea for a new feature or an improvement to an existing one? Please open an issue to discuss it first. This allows us to coordinate efforts and ensure it aligns with the project's vision.
27+
28+
### Your First Code Contribution
29+
Unsure where to begin contributing to StackCode? A great place to start is by looking through issues tagged with `good-first-issue` or `help-wanted`. These are tasks that have been identified as good entry points for new contributors.
30+
31+
## Development Setup
32+
33+
To get the project running locally for development:
34+
35+
1. **Clone the repository:**
36+
```bash
37+
git clone https://github.com/YagoBorba/StackCode.git
38+
cd StackCode
39+
```
40+
41+
2. **Install dependencies:** We use `npm` workspaces. This single command will install dependencies for all packages in the monorepo.
42+
```bash
43+
npm install
44+
```
45+
46+
3. **Build the project:** This command compiles all TypeScript packages.
47+
```bash
48+
npm run build
49+
```
50+
51+
You can now test your local changes by running the CLI from the root of the project:
52+
```bash
53+
node packages/cli/dist/index.js <command>
54+
```
55+
56+
## Git Workflow and Pull Requests
57+
58+
We use the **Gitflow** workflow. All development for new features and bugfixes should happen on branches created from the `develop` branch.
59+
60+
1. Create a feature branch from `develop`:
61+
```bash
62+
git checkout -b feature/your-awesome-feature develop
63+
```
64+
For documentation, use:
65+
```bash
66+
git checkout -b docs/what-you-are-documenting develop
67+
```
68+
69+
2. Make your changes and commit them.
70+
3. Push your branch to GitHub.
71+
4. Open a Pull Request from your branch to the `develop` branch.
72+
5. Ensure all CI checks (build and tests) are passing.
73+
74+
## Coding Style and Principles
75+
76+
- **Clean Code:** Write code that is easy to read and understand.
77+
- **SOLID Principles:** Follow SOLID principles for robust design.
78+
- **Modularity:** Keep functions and modules focused on a single responsibility.
79+
- **Documentation:** Use TSDoc-style `docstrings` (`/** ... */`) for all exported functions, classes, and types.
80+
81+
## Commit Message Guidelines
82+
83+
We use **Conventional Commits** with emojis. This helps keep our history clean and automates our release process. Please follow the format we have established in our collaboration.
84+
85+
**Example:**
86+
```
87+
feat(cli): ✨ add interactive menu to git command
88+
fix(core): 🐛 correct relative path in test file
89+
docs(readme): 📝 update installation instructions
90+
```
91+
92+
## Testing
93+
94+
- Add unit tests with **Vitest** for any new logic, especially in the `@stackcode/core` package.
95+
- Place test files in the `test/` directory, following the existing structure.
96+
- Ensure all tests pass by running:
97+
```bash
98+
npm test
99+
```
100+
101+
Our CI pipeline will run these tests automatically on your PR.
102+
103+
Thank you again for your interest in contributing!

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 Yago Azevedo Borba
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 88 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -1,89 +1,123 @@
11
<a name="readme-top"></a>
22

33
<div align="center">
4-
<br/>
5-
<br/>
6-
<h1> Welcome to {{projectName}} </h1>
7-
<p>
8-
{{description}}
9-
</p>
10-
</div>
4+
5+
<h1 align="center">StackCode</h1>
6+
7+
<br>
8+
9+
# Welcome to the StackCode repository
1110

1211
---
1312

14-
## 📖 About The Project
13+
**Ever felt the tedious grind of setting up new projects, enforcing conventions, and managing releases?** <br/>
14+
We believe developers should focus on creating, not on repetitive boilerplate and configuration. That's why we built **StackCode**: the developer's automated Ops Assistant. <br/>
15+
With intelligent scaffolding, guided commits, a simplified Gitflow, and automated releases, your workflow is about to get a major upgrade. <br/>
16+
**Your only frustration will be not having this from the start.** 😉
17+
18+
[ci-shield]: https://github.com/YagoBorba/StackCode/actions/workflows/ci.yml/badge.svg?branch=develop
19+
[ci-link]: https://github.com/YagoBorba/StackCode/actions/workflows/ci.yml
20+
[npm-shield]: https://img.shields.io/npm/v/stackcode-cli?style=flat-square&logo=npm&labelColor=black&color=CB3837
21+
[npm-link]: #
22+
[license-shield]: https://img.shields.io/github/license/YagoBorba/StackCode?style=flat-square&logo=github&labelColor=black&color=508CF9
23+
[license-link]: https://github.com/YagoBorba/StackCode/blob/develop/LICENSE
24+
25+
</br>
26+
27+
</div>
28+
29+
## ❤️ About the Project
1530

1631
> [!IMPORTANT]
17-
> This section should explain the purpose and motivation behind your project. What problem does it solve? What makes your project special? Why did you build it?
32+
> StackCode was born from a simple idea: **professional DevOps practices shouldn't be complicated.** If you agree, star this repository to give us a boost! ⭐️
1833
19-
### Built With
34+
StackCode is a powerful, opinionated CLI designed to bring consistency, quality, and automation to your development lifecycle. From the first line of code to the final release tag, StackCode is there to handle the tedious tasks, letting you focus on what truly matters: building great software.
2035

21-
This section should list any major frameworks/libraries used to bootstrap your project.
36+
Our goal is to make best practices the easiest path.
2237

23-
* [![React][React.js]][React-url]
24-
* [![Node.js][Node.js]][Node-url]
25-
* [![TypeScript][TypeScript]][TypeScript-url]
38+
## ✨ What Can StackCode Do?
2639

27-
<br/>
40+
StackCode is a suite of tools designed to work together seamlessly:
2841

29-
## 🚀 Getting Started
42+
* 🚀 **Effortless Project Scaffolding (`init`):**
43+
Generate a complete, production-ready project structure in seconds. Starts with a professional Node.js + TypeScript stack, with more to come.
44+
45+
* 📝 **Intelligent File Generation (`generate`):**
46+
Need a `.gitignore`? Don't just get one—get a perfect one. Our composable template engine combines rules for your stack, IDE, and tools (like Docker) into a single, organized file.
3047

31-
To get a local copy up and running, follow these simple steps.
48+
* 💬 **Guided Conventional Commits (`commit`):**
49+
Never write a non-compliant commit message again. Our interactive wizard guides you through the Conventional Commits specification, ensuring a clean and readable Git history.
3250

33-
### Prerequisites
51+
* 🔗 **Simplified Gitflow (`git`):**
52+
Forget memorizing branch names. Use `stc git start` and `stc git finish` to manage feature branches with ease. Our interactive menu makes the process foolproof.
3453

35-
Make sure you have the following installed on your machine.
36-
* npm
37-
```sh
38-
npm install npm@latest -g
39-
```
54+
* 🔖 **Automated Versioning & Releases (`release`):**
55+
This is where the magic happens. The `release` command analyzes your commits, automatically determines the next semantic version (`patch`, `minor`, `major`), updates all `package.json` files, generates a `CHANGELOG.md`, and creates the corresponding commit and Git tag.
4056

41-
### Installation
57+
* ✅ **Guaranteed Commit Quality (`validate`):**
58+
Integrates seamlessly with Husky git hooks. The `stc validate` command ensures that no non-conventional commit ever makes it into your repository.
4259

43-
1. Clone the repo
44-
```sh
45-
git clone [https://github.com/](https://github.com/){{githubUsername}}/{{repoName}}.git
46-
```
60+
* ⚙️ **Flexible Configuration (`config`):**
61+
Manage global preferences (like language) and project-specific settings (like enabling commit validation) with a simple, interactive command.
4762

48-
2. Install NPM packages
49-
```sh
50-
{{installCommand}}
51-
```
63+
## 🛠️ Under the Hood (Main Technologies)
5264

53-
## 🛠️ Usage
65+
* **[TypeScript](https://www.typescriptlang.org/)**: For a robust, type-safe, and maintainable codebase.
66+
* **[Node.js](https://nodejs.org/)**: The runtime environment for our powerful backend logic.
67+
* **[Yargs](https://yargs.js.org/)**: For building a clean, professional, and extensible command-line interface.
68+
* **[Inquirer](https://github.com/SBoudrias/Inquirer.js/)**: To create the intuitive and interactive prompts that guide the user.
69+
* **[Vitest](https://vitest.dev/)**: For a fast, modern, and reliable testing suite that guarantees our core logic is solid.
70+
* **[GitHub Actions](https://github.com/features/actions)**: For our CI pipeline that automatically builds and tests every Pull Request.
5471

55-
Use this space to show useful examples of how a project can be used. Additional screenshots, code examples and demos work well in this space. You may also link to more resources.
72+
## 🚀 Getting Started
5673

57-
For more examples, please refer to the Documentation
74+
There are two primary ways to use StackCode, depending on your needs.
5875

59-
## 🚣️ Roadmap
76+
### Global Installation (For Convenience)
6077

61-
- [ ] Feature 1
62-
- [ ] Feature 2
63-
- [ ] Feature 3
78+
This is the recommended approach for everyday use, especially for commands like `stc init`.
6479

65-
See the open issues for a full list of proposed features (and known issues).
80+
1. Install the CLI globally using npm:
81+
```bash
82+
npm install -g @stackcode/cli # Replace with your actual package name on npm
83+
```
84+
2. You can now run `stc` from any directory on your system!
85+
```bash
86+
stc init
87+
```
6688

67-
## 🤝 Contributing
89+
### Local Installation (For Teams)
6890

69-
Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
91+
This is the best approach for ensuring everyone on a project uses the exact same version of the tool, which is critical for features like `stc commit` and `stc release`.
7092

71-
If you have a suggestion that would make this better, please fork the repo and create a pull request.
93+
1. Install the CLI as a dev dependency in your project:
94+
```bash
95+
npm install --save-dev @stackcode/cli # Replace with your package name
96+
```
97+
2. Run commands using `npx`:
98+
```bash
99+
npx stc commit
100+
```
72101

73-
- Fork the Project
74-
- Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
75-
- Commit your Changes (`git commit -m 'feat: Add some AmazingFeature'`)
76-
- Push to the Branch (`git push origin feature/AmazingFeature`)
77-
- Open a Pull Request
102+
## 🤝 Want to Contribute?
78103

79-
## 📝 License
104+
Awesome! StackCode is an open-source project, and we welcome contributions.
80105

81-
Distributed under the {{license}} License. See LICENSE.txt for more information.
106+
To get started, please read our **[Contribution Guide](CONTRIBUTING.md)**. It has everything you need to know about our workflow, code standards, and how to submit your pull requests.
82107

83-
## ✍️ Contact
108+
## 📝 License
109+
110+
This project is licensed under the **MIT License**. See the [LICENSE](LICENSE) file for more details.
84111

85-
{{authorName}} - @your_twitter
112+
---
86113

87-
Project Link: https://github.com/{{githubUsername}}/{{repoName}}
114+
<div align="right">
115+
<a href="#readme-top">Back to Top</a>
116+
</div>
88117

89-
[back to top]: #readme-top
118+
[ci-shield]: https://github.com/YagoBorba/StackCode/actions/workflows/ci.yml/badge.svg
119+
[ci-link]: https://github.com/YagoBorba/StackCode/actions/workflows/ci.yml
120+
[npm-shield]: https://img.shields.io/npm/v/@stackcode/cli?style=flat-square&logo=npm&labelColor=black&color=CB3837
121+
[npm-link]: https://www.npmjs.com/package/@stackcode/cli
122+
[license-shield]: https://img.shields.io/github/license/YagoBorba/StackCode?style=flat-square&logo=github&labelColor=black&color=508CF9
123+
[license-link]: https://github.com/YagoBorba/StackCode/blob/develop/LICENSE

‎packages/cli/README.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# @stackcode/cli
2+
3+
This package is the user-facing entry point and the user interface (UI) layer for the StackCode toolkit. It is responsible for parsing user commands, gathering input through interactive prompts, and orchestrating calls to the `@stackcode/core` engine to execute the requested logic.
4+
5+
## Key Responsibilities
6+
7+
- **Command Parsing:** Uses the **Yargs** library to define, parse, and validate all user-facing commands, arguments, and options.
8+
- **Interactive Experience:** Leverages the **Inquirer** library to create intuitive, interactive wizards and prompts that guide the user through complex workflows like `init` and `commit`.
9+
- **User Feedback:** Provides clear, colorful, and helpful feedback to the user in the terminal, using the **Chalk** library.
10+
- **Orchestration:** Acts as the "cockpit" of the application, calling the powerful, well-tested functions exported by the `@stackcode/core` package to do the actual work.
11+
12+
## Command Structure
13+
14+
The command-line interface is designed to be modular and easy to extend.
15+
16+
- **`src/index.ts`**: The main entry point that initializes the i18n system and registers all available commands with Yargs.
17+
- **`src/commands/`**: This directory contains the implementation for each top-level command. Each file exports a `get<CommandName>Command` function that returns a Yargs `CommandModule`.
18+
- `init.ts`: Handles the project scaffolding wizard.
19+
- `generate.ts`: Handles the generation of individual files like `.gitignore`.
20+
- `commit.ts`: Provides the interactive conventional commit wizard.
21+
- `git.ts`: Orchestrates the Gitflow subcommands.
22+
- `release.ts`: Manages the automated release process.
23+
- `config.ts`: Manages global and local configuration.
24+
- `validate.ts`: Validates commit messages, typically used by Husky.
25+
- **`src/commands/git_sub/`**: Contains the logic for subcommands of the `git` command (e.g., `start.ts`, `finish.ts`).
26+
27+
## How to Add a New Command
28+
29+
Adding a new command to StackCode is straightforward:
30+
31+
1. Create a new file for your command in the `src/commands/` directory (e.g., `new-command.ts`).
32+
2. Inside the new file, create and export a function `getNewCommandCommand` that returns a `CommandModule` object. This object should define the `command`, `describe`, `builder` (for arguments), and `handler` (the command's logic).
33+
3. Implement the command's logic within the `handler`. For any complex operations, add the core logic to the `@stackcode/core` package and call it from your handler.
34+
4. Open `src/index.ts` and import your new command function.
35+
5. Register your new command in the Yargs chain by adding `.command(getNewCommandCommand())`.
36+
6. Build the project with `npm run build` and test your new command.
37+
38+
## Relationship with `@stackcode/core`
39+
40+
The `cli` package is intentionally "thin." It contains very little business logic. Its primary role is to manage the user interface and then call functions from `@stackcode/core` to perform the actual work. This clean separation of concerns is a core architectural principle of this project, making the entire system easier to maintain, test, and extend.

‎packages/cli/package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "@stackcode/cli",
3-
"version": "1.4.0",
3+
"version": "1.0.0",
44
"description": "The Command-Line Interface for StackCode",
55
"type": "module",
66
"main": "dist/index.js",

0 commit comments

Comments
 (0)