Skip to content

Commit 1af7c06

Browse files
d-sys-admind-sys-admin
committed
docs: add doc site #2 
1 parent 802b28c commit 1af7c06

File tree

18 files changed

+1470
-1
lines changed

18 files changed

+1470
-1
lines changed

‎.github/workflows/docs.yml‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
name: docs
2+
on:
3+
push:
4+
branches:
5+
- master
6+
- main
7+
permissions:
8+
contents: write
9+
jobs:
10+
deploy:
11+
runs-on: ubuntu-latest
12+
steps:
13+
- uses: actions/checkout@v4
14+
- name: Configure Git Credentials
15+
run: |
16+
git config user.name github-actions[bot]
17+
git config user.email 41898282+github-actions[bot]@users.noreply.github.com
18+
- uses: actions/setup-python@v5
19+
with:
20+
python-version: 3.x
21+
- run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
22+
- uses: actions/cache@v4
23+
with:
24+
key: mkdocs-material-${{ env.cache_id }}
25+
path: .cache
26+
restore-keys: |
27+
mkdocs-material-
28+
- run: pip install mkdocs mkdocs-terminal mkdocs-git-revision-date-plugin 'mkdocs-spellcheck[symspellpy]' mkdocs-llmstxt mkdocs-rss-plugin mkdocs-ultralytics-plugin
29+
- run: mkdocs gh-deploy --force

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,6 @@
11
node_modules
22
.env
3+
.DS_Store
4+
.site
5+
site
6+
.cache

‎README.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
11
# openai summarize diff action
22
[![node.js ci](https://github.com/captradeoff/openai-summarize-diff-action/actions/workflows/node.js.yml/badge.svg)](https://github.com/captradeoff/openai-summarize-diff-action/actions/workflows/node.js.yml)
3-
![GitHub License](https://img.shields.io/github/license/captradeoff/openai-summarize-diff-action)
3+
![github license](https://img.shields.io/github/license/captradeoff/openai-summarize-diff-action)
4+
[![github stars](https://img.shields.io/github/stars/captradeoff/openai-summarize-diff-action?style=social)](https://github.com/captradeoff/openai-summarize-diff-action/stargazers)
5+
[![github forks](https://img.shields.io/github/forks/captradeoff/openai-summarize-diff-action?style=social)](https://github.com/captradeoff/openai-summarize-diff-action/network/members)
6+
[![twitter follow](https://img.shields.io/twitter/follow/captradeoff?style=social)](https://twitter.com/captradeoff)
47

58
this github action receives a git diff (e.g., a pr diff) and uses openai to summarize and explain the changes made in that diff in a clear, concise way.
69

‎docs/configuration.md‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
---
2+
hide:
3+
- revision_date
4+
- revision_history
5+
---
6+
7+
# configuration options
8+
9+
this page documents all the configuration options available for the openai summarize diff action.
10+
11+
## input parameters
12+
13+
the action accepts the following inputs, which can be specified in your workflow file:
14+
15+
| parameter | required | default | description |
16+
|-----------|----------|---------|-------------|
17+
| `diff` | yes | - | the git diff to be explained. typically generated via `git diff` command. |
18+
| `apikey` | yes | - | your openai api key. should be stored as a secret. |
19+
| `examplePostSummary` | no | "update the code with new features: parallelisation, caching, and better error handling" | an example summary to guide the model's output style. |
20+
| `maxTokens` | no | 30 | maximum number of tokens to generate. this affects the length of the generated explanation. |
21+
| `maxCharacters` | no | 140 | maximum characters in the generated explanation. useful for ensuring the explanation fits in limited spaces. |
22+
23+
## detailed parameter information
24+
25+
### `diff`
26+
27+
the git diff to be explained. this should be the output from a git diff command. you'll typically generate this in your workflow using a command like:
28+
29+
```bash
30+
git diff origin/${{ github.event.pull_request.base.ref }}..HEAD
31+
```
32+
33+
the diff should be provided in the standard git diff format:
34+
35+
```diff
36+
diff --git a/file.js b/file.js
37+
index 123..456 789
38+
--- a/file.js
39+
+++ b/file.js
40+
@@ -1,3 +1,4 @@
41+
const a = 1;
42+
+const b = 2;
43+
const c = 3;
44+
```
45+
46+
### `apikey`
47+
48+
your openai api key. this should be stored as a github repository secret and referenced in your workflow like this:
49+
50+
```yaml
51+
apikey: ${{ secrets.OPENAI_API_KEY }}
52+
```
53+
54+
never hardcode your api key directly in the workflow file.
55+
56+
### `examplePostSummary`
57+
58+
an example summary to guide the model's output style. this helps the openai model understand the tone, format, and style you want for the generated explanation.
59+
60+
examples:
61+
62+
- `"feat: added user authentication and improved error handling"`
63+
- `"fix: resolved memory leak in data processing pipeline"`
64+
- `"refactor: simplified API response handling for better maintainability"`
65+
66+
### `maxTokens`
67+
68+
maximum number of tokens to generate. openai models use tokens, which are chunks of text (roughly 4 characters per token in english). this parameter limits the length of the generated explanation.
69+
70+
recommended values:
71+
- short summaries: 20-30
72+
- medium explanations: 50-100
73+
- detailed explanations: 100-200
74+
75+
note that higher values may result in higher api costs.
76+
77+
### `maxCharacters`
78+
79+
maximum characters in the generated explanation. this parameter ensures the explanation fits within specific character limits (like tweet length, commit message limits, etc.)
80+
81+
recommended values:
82+
- tweet-like: 140-280
83+
- commit message: ~50-72
84+
- pr comment: 500-1000
85+
86+
## output parameters
87+
88+
| parameter | description |
89+
|-----------|-------------|
90+
| `explanation` | the generated explanation of the diff. |
91+
92+
## usage examples
93+
94+
### basic usage
95+
96+
```yaml
97+
- name: Explain Diff
98+
id: explain
99+
uses: captradeoff/openai-summarize-diff-action@main
100+
with:
101+
diff: ${{ env.DIFF }}
102+
apikey: ${{ secrets.OPENAI_API_KEY }}
103+
```
104+
105+
### custom summary style
106+
107+
```yaml
108+
- name: Explain Diff
109+
id: explain
110+
uses: captradeoff/openai-summarize-diff-action@main
111+
with:
112+
diff: ${{ env.DIFF }}
113+
apikey: ${{ secrets.OPENAI_API_KEY }}
114+
examplePostSummary: "feat: updated api with improved performance and better error messages"
115+
```
116+
117+
### longer output
118+
119+
```yaml
120+
- name: Explain Diff
121+
id: explain
122+
uses: captradeoff/openai-summarize-diff-action@main
123+
with:
124+
diff: ${{ env.DIFF }}
125+
apikey: ${{ secrets.OPENAI_API_KEY }}
126+
maxTokens: 100
127+
maxCharacters: 500
128+
```
129+
130+
## using the output
131+
132+
you can use the `explanation` output in subsequent steps:
133+
134+
```yaml
135+
- name: Output explanation
136+
run: echo "${{ steps.explain.outputs.explanation }}"
137+
```
138+
139+
or add it as a pr comment:
140+
141+
```yaml
142+
- name: Post comment
143+
uses: actions/github-script@v7
144+
with:
145+
github-token: ${{ secrets.GITHUB_TOKEN }}
146+
script: |
147+
github.rest.issues.createComment({
148+
issue_number: context.issue.number,
149+
owner: context.repo.owner,
150+
repo: context.repo.repo,
151+
body: `## 🤖 AI Summary of Changes\n\n${{ steps.explain.outputs.explanation }}`
152+
});
153+
```
154+
155+
## best practices
156+
157+
1. **store api keys securely**: always use github secrets for your openai api key.
158+
2. **optimize token usage**: use the minimum number of tokens needed to get a good summary to minimize costs.
159+
3. **provide example summaries**: for more consistent results, provide example summaries that match your desired style.
160+
4. **filter large diffs**: consider filtering out large auto-generated files from diffs for better results.
161+
5. **handle error cases**: add error handling in your workflow for cases where the openai api might fail.

‎docs/contributing.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
---
2+
hide:
3+
- revision_date
4+
- revision_history
5+
---
6+
7+
# contributing guide
8+
9+
thank you for your interest in contributing to the openai summarize diff action! this document provides guidelines and instructions for contributing to this project.
10+
11+
## code of conduct
12+
13+
we expect all contributors to follow our code of conduct. please be respectful and considerate of others when contributing to this project.
14+
15+
## how to contribute
16+
17+
there are many ways to contribute to this project:
18+
19+
1. **report bugs**: if you find a bug, please [create an issue](https://github.com/captradeoff/openai-summarize-diff-action/issues/new) with details on how to reproduce it.
20+
21+
2. **suggest features**: if you have an idea for a new feature, [create an issue](https://github.com/captradeoff/openai-summarize-diff-action/issues/new) with your suggestion.
22+
23+
3. **submit pull requests**: if you'd like to fix a bug or implement a feature, submit a pull request with your changes.
24+
25+
## development setup
26+
27+
to set up your development environment:
28+
29+
1. fork the repository on github.
30+
31+
2. clone your fork locally:
32+
```bash
33+
git clone https://github.com/yourusername/openai-summarize-diff-action.git
34+
cd openai-summarize-diff-action
35+
```
36+
37+
3. install dependencies:
38+
```bash
39+
npm install
40+
```
41+
42+
4. create a branch for your changes:
43+
```bash
44+
git checkout -b my-feature-branch
45+
```
46+
47+
5. make your changes and commit them with a clear commit message.
48+
49+
6. push your branch to your fork:
50+
```bash
51+
git push origin my-feature-branch
52+
```
53+
54+
7. create a pull request from your fork to the main repository.
55+
56+
## coding standards
57+
58+
- follow the existing code style and formatting conventions.
59+
- write clear, concise comments and commit messages.
60+
- add tests for new features or bug fixes.
61+
- ensure all tests pass before submitting a pull request.
62+
- update documentation as needed.
63+
64+
## release process
65+
66+
the release process is managed by the project maintainers. the general workflow is:
67+
68+
1. changes are merged into the main branch.
69+
2. maintainers decide when to create a new release based on the changes.
70+
3. a new version is tagged according to [semantic versioning](https://semver.org/).
71+
4. a github release is created with release notes.
72+
73+
## license
74+
75+
by contributing to this project, you agree that your contributions will be licensed under the project's license.
76+
77+
## questions and acknowledgements
78+
79+
if you have any questions about contributing, please [open an issue](https://github.com/captradeoff/openai-summarize-diff-action/issues/new) or contact the project maintainers.
80+
81+
thank you for contributing to the openai summarize diff action!

0 commit comments

Comments
 (0)