From 44ddd56dd1881f84d020ff813ccef8341ce01100 Mon Sep 17 00:00:00 2001 From: tytv2 Date: Sat, 11 Apr 2026 20:42:08 +0700 Subject: [PATCH] docs: add CONTRIBUTING, CODE_OF_CONDUCT, issue/PR templates, dependabot, update README installation --- .github/ISSUE_TEMPLATE/bug_report.md | 39 ++++++++ .github/ISSUE_TEMPLATE/feature_request.md | 31 ++++++ .github/PULL_REQUEST_TEMPLATE.md | 22 ++++ .github/dependabot.yml | 8 ++ CODE_OF_CONDUCT.md | 33 ++++++ CONTRIBUTING.md | 117 ++++++++++++++++++++++ README.md | 65 +++++++++--- 7 files changed, 299 insertions(+), 16 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 .github/dependabot.yml create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..9a8734c --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,39 @@ +--- +name: Bug Report +about: Report a bug in the Greenode CLI +title: "[Bug] " +labels: bug +assignees: '' +--- + +## Description + +A clear and concise description of the bug. + +## Steps to reproduce + +```bash +grn vks ... +``` + +## Expected behavior + +What you expected to happen. + +## Actual behavior + +What actually happened. Include the full error output. + +``` +Error: ... +``` + +## Environment + +- OS: [e.g. macOS 15.2, Ubuntu 24.04, Windows 11] +- Python version: [e.g. 3.13.5] +- Greenode CLI version: [output of `grn --version`] + +## Additional context + +Any other context about the problem (config, region, etc.) diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..cde52f8 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,31 @@ +--- +name: Feature Request +about: Suggest a new feature or improvement +title: "[Feature] " +labels: feature +assignees: '' +--- + +## Description + +A clear description of the feature you'd like to see. + +## Use case + +Why do you need this feature? What problem does it solve? + +## Proposed solution + +How you think this should work: + +```bash +grn vks --arg value +``` + +## Alternatives considered + +Any alternative solutions or workarounds you've considered. + +## Additional context + +Any other context, screenshots, or references. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..4cd7165 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,22 @@ +## Description + +Brief description of what this PR does. + +## Type of change + +- [ ] Bug fix +- [ ] New feature +- [ ] Enhancement +- [ ] Breaking change +- [ ] Documentation + +## Checklist + +- [ ] Tests added/updated and passing (`python -m pytest tests/ -v`) +- [ ] Changelog entry added (`./scripts/new-change`) +- [ ] Documentation updated (if applicable) +- [ ] Code follows existing patterns + +## Related issues + +Closes # diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..72b2521 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,8 @@ +version: 2 +updates: + - package-ecosystem: "pip" + directory: "/" + schedule: + interval: "weekly" + labels: + - "dependencies" diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..99ca9d6 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,33 @@ +# Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone. + +## Our Standards + +Examples of behavior that contributes to a positive environment: + +* Being respectful of differing viewpoints and experiences +* Giving and gracefully accepting constructive feedback +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior: + +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information without explicit permission +* Other conduct which could reasonably be considered inappropriate + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the project maintainers. All complaints will be reviewed and +investigated and will result in a response that is deemed necessary and +appropriate to the circumstances. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..68869f8 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,117 @@ +# Contributing to Greenode CLI + +Thank you for your interest in contributing to the Greenode CLI! + +## Getting Started + +### Prerequisites + +- Python 3.10 or later +- Git + +### Setup development environment + +```bash +git clone https://github.com/vngcloud/greennode-cli.git +cd greennode-cli +python -m venv .venv +source .venv/bin/activate # On Windows: .venv\Scripts\activate +pip install -e ".[dev]" +``` + +### Run tests + +```bash +python -m pytest tests/ -v +``` + +## Development Workflow + +### 1. Create a feature branch + +```bash +git checkout develop +git pull +git checkout -b feat/your-feature-name +``` + +### 2. Make changes and test + +```bash +# Write code +# Write tests +python -m pytest tests/ -v +``` + +### 3. Add a changelog entry + +Every PR should include a changelog fragment: + +```bash +./scripts/new-change -t feature -c vks -d "Add your feature description" +``` + +Change types: `feature`, `bugfix`, `enhancement`, `api-change` + +### 4. Commit and push + +Follow [Conventional Commits](https://www.conventionalcommits.org/): + +``` +feat(vks): add describe-events command +fix(auth): fix token refresh race condition +docs(readme): update installation instructions +``` + +### 5. Create a Pull Request + +- PR to `develop` for testing +- PR to `main` when release-ready +- CI must pass before merge +- At least 1 approval required + +## Adding a New Service + +Other product teams can add CLI commands: + +1. Create `grncli/customizations//` +2. Write commands extending `BasicCommand` (see `grncli/customizations/vks/` for reference) +3. Register in `grncli/handlers.py` + +### Command template + +```python +from grncli.customizations.commands import BasicCommand, display_output + +class MyCommand(BasicCommand): + NAME = 'my-command' + DESCRIPTION = 'Description of my command' + ARG_TABLE = [ + {'name': 'my-arg', 'help_text': 'Argument description', 'required': True}, + ] + + def _run_main(self, parsed_args, parsed_globals): + client = self._session.create_client('my-service') + result = client.get('/v1/my-endpoint') + display_output(result, parsed_globals) + return 0 +``` + +## Code Style + +- All source code text (messages, comments, descriptions) must be in English +- Follow existing patterns in the codebase +- Add tests for new features +- Validate user inputs (especially IDs used in URLs) +- Use `--dry-run` for create/update/delete commands +- Add `--force` to skip confirmation on delete commands + +## Reporting Issues + +- Use [GitHub Issues](https://github.com/vngcloud/greennode-cli/issues) +- Search existing issues before creating a new one +- Use the provided issue templates + +## License + +By contributing, you agree that your contributions will be licensed under the [Apache License 2.0](LICENSE). diff --git a/README.md b/README.md index 5b9fb20..128cbdd 100644 --- a/README.md +++ b/README.md @@ -4,44 +4,77 @@ Universal Command Line Interface for Greenode (VNG Cloud). ## Installation -### Standard install (pip) +### Prerequisites + +- Python 3.10 or later +- `pip` 21.0 or greater +- `setuptools` 68.0 or greater + +### Install from PyPI + +The recommended way to install the Greenode CLI is to use `pip` in a `virtualenv`: + +```bash +python -m pip install grncli +``` + +or, if you are not installing in a `virtualenv`, to install globally: + +```bash +sudo python -m pip install grncli +``` + +or for your user: + +```bash +python -m pip install --user grncli +``` + +If you have the grncli package installed and want to upgrade to the latest version: + +```bash +python -m pip install --upgrade grncli +``` + +### Install from source ```bash -pip install . +git clone https://github.com/vngcloud/greennode-cli.git +cd greennode-cli +python -m pip install . ``` -### Development install +To install with development dependencies: ```bash -pip install -e ".[dev]" +python -m pip install -e ".[dev]" ``` -### Standalone install (isolated virtualenv) +### Bundled installer + +On Linux and macOS, the Greenode CLI can be installed using a standalone installer that creates an isolated virtualenv: ```bash ./scripts/install ``` -This creates a virtualenv at `~/.local/lib/greenode` and symlinks `grn` to `~/.local/bin/`. +This installs to `~/.local/lib/greenode` and symlinks `grn` to `~/.local/bin/`. Make sure `~/.local/bin` is in your `PATH`. + +### Offline install -### Offline install (bundle) +For environments without internet access, you can build a self-contained bundle: ```bash -# Build bundle (requires internet) +# On a machine with internet access ./scripts/make-bundle -# Install on target machine (no internet required) -unzip dist/grncli-bundle.zip +# Transfer dist/grncli-bundle.zip to target machine, then: +unzip grncli-bundle.zip cd grncli-bundle ./install-offline ``` -### CI install - -```bash -./scripts/ci/install # Build wheel and install -./scripts/ci/run-tests # Run test suite -``` +If you want to run the `develop` branch of the Greenode CLI, see the [Development Guide](docs/DEVELOPMENT.md). ## Configuration