Skip to content

Commit 76a1f9f

Browse files
dlvhdrdlvhdr
authored
docs: ai policy (#116)
1 parent 0957bb1 commit 76a1f9f

5 files changed

Lines changed: 179 additions & 0 deletions

File tree

‎.github/ISSUE_TEMPLATE/bug_report.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
name: Bug report
3+
about: Create a report to help us improve
4+
title: "[BUG]"
5+
labels: bug
6+
assignees: ""
7+
---
8+
9+
**Describe the bug**
10+
A clear and concise description of what the bug is.
11+
12+
**To Reproduce**
13+
Steps to reproduce the behavior:
14+
15+
1. Go to '...'
16+
2. Click on '....'
17+
3. Scroll down to '....'
18+
4. See error
19+
20+
**Expected behavior**
21+
A clear and concise description of what you expected to happen.
22+
23+
**Screenshots**
24+
If applicable, add screenshots to help explain your problem.
25+
26+
**Desktop (please complete the following information):**
27+
28+
- OS: [e.g. Mac]
29+
- Version: what version are you using?
30+
- Terminal Emulator
31+
- Using tmux?

‎.github/ISSUE_TEMPLATE/feature_request.md‎

Whitespace-only changes.

‎.github/pull_request_template.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Summary
2+
3+
- [] Closes issue #...
4+
- [] I have read the [CONTIBUTING.md](../CONTRIBUTING.md) and [AI_POLICY.md](../AI_POLICY.md) guides
5+
6+
## How Did You Test this Change?
7+
8+
## Images/Videos
9+
10+
<!-- if relevant, please include any relevant images that show off how your feature is
11+
working -->

‎AI_POLICY.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# AI Usage Policy
2+
3+
This project has strict rules for AI usage:
4+
5+
- **All AI usage in any form must be disclosed.** You must state
6+
the tool you used (e.g. Claude Code, Cursor, Amp) along with
7+
the extent that the work was AI-assisted.
8+
9+
- **The human-in-the-loop must fully understand all code.** If you
10+
can't explain what your changes do and how they interact with the
11+
greater system without the aid of AI tools, do not contribute
12+
to this project.
13+
14+
- **Issues and discussions can use AI assistance but must have a full
15+
human-in-the-loop.** This means that any content generated with AI
16+
must have been reviewed _and edited_ by a human before submission.
17+
AI is excellent at being overly verbose and including noise that
18+
distracts from the main point. Humans must do their research and
19+
trim this down.
20+
21+
- **No AI-generated media is allowed (art, images, videos, audio, etc.).**
22+
Text and code are the only acceptable AI-generated content, per the
23+
other rules in this policy.
24+
25+
These rules apply only to outside contributions. Maintainers
26+
are exempt from these rules and may use AI tools at their discretion;
27+
they've proven themselves trustworthy to apply good judgment.
28+
29+
## There Are Humans Here
30+
31+
Please remember that this project is maintained by humans.
32+
33+
Every discussion, issue, and pull request is read and reviewed by
34+
humans (and sometimes machines, too). It is a boundary point at which
35+
people interact with each other and the work done. It is rude and
36+
disrespectful to approach this boundary with low-effort, unqualified
37+
work, since it puts the burden of validation on the maintainer.
38+
39+
In a perfect world, AI would produce high-quality, accurate work
40+
every time. But today, that reality depends on the driver of the AI.
41+
And today, most drivers of AI are just not good enough. So, until either
42+
the people get better, the AI gets better, or both, we have to have
43+
strict rules to protect maintainers.

‎CONTRIBUTING.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
# Contributing To `diffnav`
2+
3+
Thank you for investing your time in contributing to our project!
4+
5+
In this guide you will get an overview of the contribution workflow from opening an issue, creating a PR, reviewing, and merging the PR.
6+
7+
## The Critical Rule
8+
9+
- The most important rule: you must understand your code. If you can't explain what your changes do and how they interact with the greater system without the aid of AI tools, do not contribute to this project.
10+
- The second most important rule: when you submit a PR you must be willing to address comments and maintain this code. Dot not submit drive-by PRs that solve your own issue without the willingness to iterate on it. Keep these in your own fork.
11+
- Using AI to write code is fine. You can gain understanding by interrogating an agent with access to the codebase until you grasp all edge cases and effects of your changes. What's not fine is submitting agent-generated slop without that understanding. Be sure to read the [AI Usage Policy](AI_POLICY.md).
12+
13+
## AI Usage
14+
15+
The project has strict rules for AI usage. Please see the [AI Usage Policy](AI_POLICY.md). This is very important.
16+
17+
## Quick Guide
18+
19+
### I Have an Idea for a Feature
20+
21+
Like bug reports, first search through both issues and discussions and try to find if your feature has already been requested. Otherwise, open a discussion in the ["Feature Requests, Ideas"](https://github.com/dlvhdr/diffnav/issues/new?template=feature_request.md) category.
22+
23+
### I've Implemented a Feature
24+
25+
- If there is an issue for the feature, open a pull request straight away.
26+
- If there is no issue, open a discussion and link to your branch.
27+
- If you want to live dangerously, open a pull request and hope for the best.
28+
29+
### I Have a Question Which Is Neither a Bug Report nor a Feature Request
30+
31+
Open a [Q&A discussion](https://github.com/dlvhdr/diffnav/discussions/categories/q-a), or join our [Discord Server](https://discord.gg/SXNXp9NctV) and ask away in the #help forum channel.
32+
33+
## Working on the Code
34+
35+
### Installing Required Tooling
36+
37+
Our project uses [Devbox](https://github.com/jetpack-io/devbox) to manage its development environment.
38+
39+
Using Devbox will get your dev environment up and running easily and make sure we're all using the same tools with the same versions.
40+
41+
- Clone this repo
42+
43+
```sh
44+
git clone git@github.com:dlvhdr/diffnav.git && cd diffnav
45+
```
46+
47+
- Install `devbox`
48+
49+
```sh
50+
curl -fsSL https://get.jetpack.io/devbox | bash
51+
```
52+
53+
- Start the `devbox` shell and run the setup (will take awhile on first time)
54+
55+
```sh
56+
devbox shell
57+
```
58+
59+
_This will create a shell where all required tools are installed._
60+
61+
- _(Optional)_ Set up `direnv` so `devbox shell` runs automatically
62+
- [direnv](https://www.jetify.com/devbox/docs/ide_configuration/direnv/) is a tool that allows setting unique environment variables per directory in your filesystem.
63+
- Install `direnv` with: `brew install direnv`
64+
- Add the following line at the end of the `~/.bashrc` file: `eval "$(direnv hook bash)"`
65+
- See [direnv's installation instructions](https://direnv.net/docs/hook.html) for other shells.
66+
- Enable `direnv` by running `direnv allow`
67+
- _(Optional)_ Install the VSCode Extension
68+
- Follow [this guide](https://www.jetify.com/devbox/docs/ide_configuration/vscode/) to set up VSCode to automatically run `devbox shell`.
69+
70+
#### Troubleshooting
71+
72+
- delete the `.devbox` directory at the project's root
73+
74+
### Navigating the Codebase
75+
76+
To navigate our codebase with confidence, familiarize yourself with:
77+
78+
- [Bubbletea](https://github.com/charmbracelet/bubbletea) - the TUI framework we're using
79+
- [The Elm architecture](https://guide.elm-lang.org/architecture/)
80+
- [charmbracelet/glow](https://github.com/charmbracelet/glow) - for parsing and presenting Markdown
81+
82+
### Debugging
83+
84+
- Write to the log by using Charm's `log` package
85+
- Tail the log by running `task logs`
86+
- Run `diffnav` in debug mode with `task debug` in another terminal window / pane
87+
88+
```go
89+
import "charm.land/log/v2"
90+
91+
// more code...
92+
93+
log.Debug("some message", "someVariable", someVariable)
94+
```

0 commit comments

Comments
 (0)