Skip to content

Commit ab27d39

Browse files
jeropjerop
authored
feat(docs): improve documentation clarity and structure (#87)
This commit significantly improves the documentation for the `run-gemini-cli` GitHub Action. The following changes are included: - Restructured the main `README.md` to be more concise and user-friendly, moving detailed configuration and authentication information to the `docs` directory. - Consolidated the authentication documentation into a single, comprehensive `docs/authentication.md` file. - Improved the `docs/observability.md` to clarify the setup process and add more details on the benefits of observability. - Refined the workflow documentation in the `workflows` directory to be more consistent and easier to understand. - Updated all links between documents to reflect the new structure.
1 parent 8030975 commit ab27d39

File tree

9 files changed

+594
-451
lines changed

9 files changed

+594
-451
lines changed

‎CONTRIBUTING.md

Lines changed: 145 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -2,62 +2,171 @@
22

33
First off, thank you for considering contributing to the run-gemini-cli!
44

5-
## Contribution Workflow
6-
7-
Here is a summary of the contribution workflow.
5+
- [Contributing to run-gemini-cli](#contributing-to-run-gemini-cli)
6+
- [Overview](#overview)
7+
- [Prerequisites](#prerequisites)
8+
- [Development Setup](#development-setup)
9+
- [Contribution Workflow](#contribution-workflow)
10+
- [Development Guidelines](#development-guidelines)
11+
- [Code Standards](#code-standards)
12+
- [Security](#security)
13+
- [Code Quality](#code-quality)
14+
- [Action Standards](#action-standards)
15+
- [Testing](#testing)
16+
- [Documentation](#documentation)
17+
- [Updating Action Inputs and Outputs](#updating-action-inputs-and-outputs)
18+
- [PR Review Process](#pr-review-process)
19+
- [Community \& Communication](#community--communication)
20+
21+
## Overview
22+
23+
This project is a composite GitHub Action that integrates Gemini AI into GitHub workflows. We welcome contributions including bug fixes, feature enhancements, documentation improvements, and new workflow examples.
24+
25+
## Prerequisites
26+
27+
Before contributing, ensure you have:
28+
29+
- Git installed on your local machine
30+
- Node.js and npm installed (for documentation generation)
31+
32+
## Development Setup
33+
34+
1. **Fork and Clone the Repository**
35+
- Fork the repository on GitHub by clicking the "Fork" button
36+
- Clone your forked repository to your local machine:
37+
```sh
38+
git clone https://github.com/YOUR_USERNAME/run-gemini-cli.git
39+
cd run-gemini-cli
40+
```
41+
42+
2. **Set Upstream Remote**
43+
- Add the original repository as the `upstream` remote:
44+
```sh
45+
git remote add upstream https://github.com/google-github-actions/run-gemini-cli.git
46+
```
47+
48+
3. **Install Dependencies**
49+
- Install the required Node.js dependencies:
50+
```sh
51+
npm install
52+
```
853

9-
1. **Fork and Clone the Repository**
10-
- Fork the repository on GitHub by clicking the "Fork" button.
11-
- Clone your forked repository to your local machine:
12-
```sh
13-
git clone https://github.com/YOUR_USERNAME/run-gemini-cli.git
14-
cd run-gemini-cli
15-
```
16-
17-
2. **Set Upstream Remote**
18-
- Add the original repository as the `upstream` remote. This will allow you to keep your fork in sync with the main project.
19-
```sh
20-
git remote add upstream https://github.com/google-github-actions/run-gemini-cli.git
21-
```
54+
## Contribution Workflow
2255

23-
3. **Create a Branch**
24-
- Create a new branch for your changes. A good branch name is descriptive of the changes you are making.
56+
1. **Create a Branch**
57+
- Create a new branch for your changes. Use a descriptive name:
2558
```sh
26-
git checkout -b your-descriptive-branch-name
59+
git checkout -b feature/your-descriptive-branch-name
2760
```
2861

29-
4. **Make Your Changes**
30-
- Now you can make your changes to the code.
31-
32-
5. **Commit Your Changes**
33-
- Once you are happy with your changes, commit them with a descriptive commit message. We follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification.
62+
2. **Make Your Changes**
63+
- Implement your changes following the [development guidelines](#development-guidelines)
64+
- If you modify `action.yml` inputs or outputs, update the documentation:
3465
```sh
35-
git add .
36-
git commit -m "feat: add new feature"
66+
npm run docs
3767
```
3868

39-
6. **Keep Your Fork Synced**
40-
- Before you push your changes, you should sync your `main` branch with the `upstream` repository.
69+
3. **Commit Your Changes**
70+
- Commit with a descriptive message following [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)
71+
72+
**Example of a detailed commit message:**
73+
```sh
74+
git commit -m "feat: add custom timeout support for workflow execution
75+
76+
Users reported workflow failures in large repositories where Gemini CLI
77+
operations exceed the default GitHub Actions timeout limit. This causes
78+
incomplete analysis and frustrating failures for complex codebases.
79+
80+
Add configurable timeout support to prevent workflow timeouts:
81+
- Enable users to set custom timeout values based on repository size
82+
- Provide graceful handling when operations approach time limits
83+
- Include clear error messages when timeouts occur
84+
- Document timeout configuration for different use cases
85+
86+
This resolves timeout issues for enterprise users with large repositories
87+
and improves the overall reliability of the action.
88+
89+
Closes #123"
90+
```
91+
92+
4. **Keep Your Fork Synced**
93+
- Sync your `main` branch with the `upstream` repository:
4194
```sh
4295
git checkout main
4396
git pull upstream main
4497
```
4598

46-
7. **Rebase Your Branch**
47-
- Now, rebase your feature branch on top of the `main` branch. This will ensure that your changes are applied on top of the latest changes from the `upstream` repository.
99+
5. **Rebase Your Branch**
100+
- Rebase your feature branch on top of the latest `main`:
48101
```sh
49-
git checkout your-descriptive-branch-name
102+
git checkout feature/your-descriptive-branch-name
50103
git rebase main
51104
```
52105

53-
8. **Push Your Changes**
54-
- Push your changes to your forked repository.
106+
6. **Push Your Changes**
107+
- Push your changes to your forked repository:
55108
```sh
56-
git push --force-with-lease origin your-descriptive-branch-name
109+
git push --force-with-lease origin feature/your-descriptive-branch-name
57110
```
58111

59-
9. **Create a Pull Request**
60-
- Now you can go to your forked repository on GitHub and create a pull request.
112+
7. **Create a Pull Request**
113+
- Go to your forked repository on GitHub and create a pull request
114+
115+
## Development Guidelines
116+
117+
When contributing to this composite GitHub Action:
118+
119+
### Code Standards
120+
121+
Follow these principles when contributing to this composite GitHub Action:
122+
123+
#### Security
124+
- **Principle of least privilege**: Request only necessary permissions
125+
- **Validate inputs**: Sanitize user inputs to prevent security issues
126+
- **Secure defaults**: Choose the most secure configuration options
127+
128+
#### Code Quality
129+
- **Clear naming**: Use descriptive variable and function names
130+
- **Error handling**: Provide meaningful error messages with context
131+
- **Shell best practices**: Write portable, robust shell scripts
132+
- **Documentation**: Keep code and documentation synchronized
133+
134+
#### Action Standards
135+
- **YAML consistency**: Use consistent formatting and structure
136+
- **Input/output documentation**: Clearly describe all parameters
137+
- **Version management**: Pin dependencies to specific versions
138+
139+
## Testing
140+
141+
Before submitting your PR:
142+
143+
- **Validate action.yml**: Ensure the manifest is valid YAML
144+
- **Test workflows**: Verify example workflows work as expected
145+
- **Check documentation**: Ensure all examples and references are accurate
146+
- **Lint shell scripts**: Use tools like `shellcheck` for script validation
147+
148+
## Documentation
149+
150+
When making changes:
151+
152+
- Update `README.md` if you modify inputs, outputs, or usage
153+
- Update workflow examples in `/workflows` directory
154+
- Add or update relevant documentation in `/docs`
155+
- Ensure all links and references are working
156+
- **Important**: If you modify `action.yml` inputs or outputs, run `npm run docs` to automatically update the documentation in `README.md`
157+
158+
### Updating Action Inputs and Outputs
159+
160+
The inputs and outputs documentation in `README.md` is automatically generated from `action.yml`. After modifying `action.yml`:
161+
162+
1. Run the documentation update script:
163+
```sh
164+
npm run docs
165+
```
166+
167+
2. This will update the `<!-- BEGIN_AUTOGEN_INPUTS -->` and `<!-- BEGIN_AUTOGEN_OUTPUTS -->` sections in `README.md`
168+
169+
3. Commit both `action.yml` and the updated `README.md` together
61170

62171
## PR Review Process
63172

0 commit comments

Comments
 (0)