Skip to content

Commit 92a70fa

Browse files
gilesknapgilesknap
authored
Merge pull request #1 from DiamondLightSource/add-devcontainer-et-al
Add devcontainer tooling, docs, and gh CLI
2 parents 3eeb80d + 97b7fb7 commit 92a70fa

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

41 files changed

+2131
-1
lines changed

‎.claude/settings.json‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
{
2+
"permissions": {
3+
"allow": [
4+
"Read",
5+
"Edit",
6+
"Write",
7+
"Bash(*)",
8+
"WebSearch",
9+
"WebFetch(*)",
10+
"mcp__claude-in-chrome__*"
11+
],
12+
"prompt": [
13+
"Bash(git push --force *)",
14+
"Bash(git reset --hard*)",
15+
"Bash(ssh *)",
16+
"Bash(scp *)",
17+
"Bash(rsync *)",
18+
"Bash(sftp *)",
19+
"Bash(wget --post* *)",
20+
"Bash(telnet *)",
21+
"Bash(mail *)",
22+
"Bash(sendmail *)"
23+
]
24+
},
25+
"hooks": {
26+
"UserPromptSubmit": [
27+
{
28+
"hooks": [
29+
{
30+
"type": "command",
31+
"command": "if [ -z \"$REMOTE_CONTAINERS\" ]; then echo 'BLOCKED: This project requires the devcontainer. Please reopen in the devcontainer before using Claude Code.'; exit 2; fi"
32+
}
33+
]
34+
}
35+
]
36+
}
37+
}

‎.claude/skills/documentation/SKILL.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
---
2+
name: documentation
3+
description: Guidelines for writing and maintaining project documentation.
4+
---
5+
6+
> **Generic skill** — This skill is project-agnostic. Do not add project-specific
7+
> references, paths, or terminology here.
8+
9+
# Documentation Skill
10+
11+
Guidelines for writing and maintaining project documentation.
12+
13+
## When to Use
14+
15+
Use this skill when:
16+
- Writing or editing documentation files in `docs/`
17+
- Reviewing documentation for correctness or completeness
18+
- Adding new documentation pages
19+
20+
## Principles
21+
22+
### Embed, don't copy
23+
24+
Never duplicate file contents into documentation. Instead, use Sphinx
25+
directives to include the real file so docs stay in sync automatically:
26+
27+
```text
28+
29+
```rst
30+
```{literalinclude} ../../robots/Meca500-R3/chain.yaml
31+
:language: yaml
32+
```
33+
```
34+
35+
36+
```
37+
38+
If a full include is too long, use `:lines:` or `:start-after:` /
39+
`:end-before:` to select a portion.
40+
41+
### Describe patterns, don't enumerate files
42+
43+
When documenting directory layouts or file sets that vary (e.g. per-robot
44+
files), describe the general structure and mention that additional files
45+
may exist. Listing every optional file creates maintenance burden and goes
46+
stale as the project evolves.
47+
48+
Good:
49+
> Individual robots may also include specs files, verification scripts,
50+
> reference images, or view mappings.
51+
52+
Bad:
53+
> ```
54+
> ├── specs.yaml
55+
> ├── verify_kinematics.py
56+
> ├── images/
57+
> │ └── *.svg / *.png
58+
> └── view_mapping.yaml
59+
> ```
60+
61+
### Keep skill and command references accurate
62+
63+
When referencing Claude Code skills (slash commands), use the actual skill
64+
name from `.claude/skills/*/SKILL.md`. If a skill is renamed or removed,
65+
update all documentation that references it.
66+
67+
### Single source of truth
68+
69+
If two docs cover the same topic, consolidate into one and link to it from
70+
the other. Avoid parallel pages that drift apart over time (e.g. a separate
71+
installation page when quick-start already covers setup).
72+
73+
### Diataxis framework
74+
75+
This project follows the [Diataxis](https://diataxis.fr) documentation
76+
framework:
77+
78+
- **Tutorials** — learning-oriented, get the user to a working result
79+
- **How-to guides** — task-oriented, practical steps for experienced users
80+
- **Explanations** — understanding-oriented, how and why things work
81+
- **Reference** — information-oriented, precise technical specifications

‎.claude/skills/memo/SKILL.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
name: memo
3+
description: Save current task state to auto-memory, then promote reusable lessons to skills and trim memory.
4+
---
5+
6+
> **Generic skill** — This skill is project-agnostic. Do not add project-specific
7+
> references, paths, or terminology here.
8+
9+
# Memo
10+
11+
Save a snapshot of current work to persistent memory, then clean up.
12+
13+
## Step 1 — Save current state
14+
15+
Write a concise summary of in-progress or recently completed work to the standard auto memory folder. Include:
16+
17+
- What was done (beamline/IOC name, module, etc.)
18+
- Current status (completed, blocked, in-progress)
19+
- Key decisions or outcomes
20+
21+
Do not duplicate information already in skills or CLAUDE.md.
22+
23+
## Step 2 — Promote to skills
24+
25+
Review the memory file for items that represent **reusable patterns or
26+
lessons** — things that would help future conversions. For each such item:
27+
28+
1. Identify which skill file it belongs in.
29+
2. Add it to the appropriate skill or create a new one if needed.
30+
3. Remove it from memory (it now lives in the skill)
31+
32+
Examples of promotable items:
33+
- A new "foot-gun" pattern
34+
- A module that needs special handling
35+
- A new critical question to ask during conversion
36+
37+
## Step 3 — Trim memory
38+
39+
Remove from memory anything that is:
40+
- Already captured in skills or CLAUDE.md
41+
- Stale or superseded by later work
42+
43+
Keep memory concise — ideally under 30 lines.

‎.devcontainer/Dockerfile‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
FROM mcr.microsoft.com/devcontainers/go:1.24
2+
3+
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /usr/local/bin/
4+
5+
RUN curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
6+
| dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg \
7+
&& echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
8+
| tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
9+
&& apt-get update && apt-get install -y gh && rm -rf /var/lib/apt/lists/*

‎.devcontainer/devcontainer.json‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
{
2+
"name": "Go Developer Container",
3+
"build": {
4+
"context": "..",
5+
"dockerfile": "Dockerfile"
6+
},
7+
"customizations": {
8+
"vscode": {
9+
"settings": {
10+
"go.lintTool": "golangci-lint",
11+
"go.lintFlags": [
12+
"--fast"
13+
]
14+
},
15+
"extensions": [
16+
"golang.go",
17+
"github.vscode-github-actions",
18+
"redhat.vscode-yaml",
19+
"ms-azuretools.vscode-docker"
20+
]
21+
}
22+
},
23+
"postCreateCommand": "go mod download && go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest && uv sync --group docs",
24+
"remoteEnv": {
25+
"PATH": "${containerWorkspaceFolder}/.venv/bin:${containerEnv:PATH}"
26+
},
27+
// Mount the parent as /workspaces so we can pip install peers as editable
28+
"workspaceMount": "source=${localWorkspaceFolder}/..,target=/workspaces,type=bind",
29+
}

‎.github/CONTRIBUTING.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# Contribute to the project
2+
3+
Contributions and issues are most welcome! All issues and pull requests are
4+
handled through [GitHub](https://github.com/DiamondLightSource/dra-usbip-driver/issues).
5+
Please check for any existing issues before filing a new one. If you have a
6+
great idea but it involves big changes, please file a ticket before making a
7+
pull request!
8+
9+
## Issue or Discussion?
10+
11+
GitHub also offers [discussions](https://github.com/DiamondLightSource/dra-usbip-driver/discussions)
12+
as a place to ask questions and share ideas. If your issue is open ended and it
13+
is not obvious when it can be "closed", please raise it as a discussion instead.
14+
15+
## Developer Information
16+
17+
It is recommended that developers use a
18+
[VSCode devcontainer](https://code.visualstudio.com/docs/devcontainers/containers).
19+
This repository contains configuration to set up a containerized development
20+
environment with all required Go tools.
21+
22+
### Prerequisites (without devcontainer)
23+
24+
- Go 1.24+
25+
- [golangci-lint](https://golangci-lint.run/)
26+
27+
### Running tests
28+
29+
```bash
30+
go test ./...
31+
```
32+
33+
### Running the linter
34+
35+
```bash
36+
golangci-lint run
37+
```
38+
39+
### Building
40+
41+
```bash
42+
make agent
43+
go build ./cmd/manager
44+
go build ./cmd/plugin
45+
```

‎.github/ISSUE_TEMPLATE/bug_report.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
name: Bug Report
3+
about: Report a bug or usability issue
4+
title: " "
5+
labels: "bug"
6+
assignees: ""
7+
---
8+
9+
Describe the bug, including a clear and concise description of the expected
10+
behaviour, the actual behavior and the context in which you encountered it.
11+
12+
**Environment:**
13+
- Kubernetes version:
14+
- Node OS:
15+
- Kernel version:
16+
- usbip tools version:
17+
18+
## Steps To Reproduce
19+
20+
1. ...
21+
2. ...
22+
3. ...
23+
24+
## Acceptance Criteria
25+
26+
- Specific criteria that will be used to judge if the issue is fixed

‎.github/ISSUE_TEMPLATE/issue.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
name: Issue
3+
about: Feature requests, design discussions and tasks
4+
title: " "
5+
labels: ""
6+
assignees: ""
7+
---
8+
9+
A brief description of the issue, including specific stakeholders and the
10+
business case where appropriate.
11+
12+
## Acceptance Criteria
13+
14+
- Specific criteria that will be used to judge if the issue is resolved

‎.github/PULL_REQUEST_TEMPLATE/pull_request_template.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
Fixes #ISSUE
2+
3+
### Instructions to reviewer on how to test:
4+
1. Do thing x
5+
2. Confirm thing y happens
6+
7+
### Checks for reviewer
8+
- [ ] Would the PR title make sense to a user on a set of release notes

‎.github/pages/index.html‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
<!DOCTYPE html>
2+
<html>
3+
4+
<head>
5+
<title>Redirecting to main branch</title>
6+
<meta charset="utf-8">
7+
<meta http-equiv="refresh" content="0; url=./master/index.html">
8+
<link rel="canonical" href="master/index.html">
9+
</head>
10+
11+
</html>

0 commit comments

Comments
 (0)