Skip to content

Commit 301cae5

Browse files
leecalcoteleecalcote
authored
Merge pull request #862 from layer5io/copilot/set-up-copilot-instructions
[.github] Set up Copilot instructions
2 parents 751f77b + 8c3ac51 commit 301cae5

File tree

1 file changed

+314
-0
lines changed

1 file changed

+314
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 314 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,314 @@
1+
# GitHub Copilot Custom Coding Agent Instructions
2+
3+
## AI Model Selection
4+
5+
**IMPORTANT**: When using GitHub Copilot, always select the most powerful AI model available (e.g., GPT-4, Claude 3.5 Sonnet, or the latest advanced model) for code generation, review, and assistance tasks. More powerful models provide better code quality, deeper understanding of context, and more accurate suggestions aligned with project standards.
6+
7+
## Project Overview
8+
9+
The Layer5 Docs website is a Hugo-based documentation site that serves as the primary documentation resource for Layer5 products, hosted at https://github.com/layer5io/docs and live at https://docs.layer5.io. It provides comprehensive documentation for Layer5 Cloud, Kanvas, and related products, offering tutorials, guides, and reference materials for users and contributors in the cloud native ecosystem.
10+
11+
## Technology Stack
12+
13+
- **Framework**: Hugo (extended version with SCSS support)
14+
- **Theme**: Docsy (Google's documentation theme)
15+
- **Language**: Go templates, HTML, CSS/SCSS, JavaScript
16+
- **Content**: Markdown with Hugo shortcodes
17+
- **Package Manager**: npm
18+
- **Node Version**: See `.nvmrc`
19+
- **Build System**: Hugo CLI, Make
20+
21+
## Core Principles
22+
23+
### 1. Minimal, Surgical Changes
24+
- Make the **smallest possible changes** to accomplish the goal
25+
- Never delete or modify working code unless absolutely necessary
26+
- Focus on precise, targeted modifications rather than wholesale rewrites
27+
- Preserve existing patterns and conventions unless explicitly changing them
28+
29+
### 2. Code Quality Standards
30+
- Follow the existing code style and patterns in the repository
31+
- Ensure proper indentation and formatting in templates and content
32+
- Write clean, readable, self-documenting code with minimal comments unless necessary for complex logic
33+
- Maintain accessibility standards (WCAG 2.1)
34+
35+
### 3. Testing and Validation
36+
- Always validate changes work before considering them complete
37+
- Build the site and verify rendered content: `make build` or `hugo`
38+
- Run the site locally: `make site` or `hugo server -D -F`
39+
- Test changes incrementally and iteratively
40+
41+
## Project Structure
42+
43+
```
44+
docs/
45+
├── .github/ # GitHub configuration and workflows
46+
├── assets/ # Site assets (CSS, JS, images)
47+
├── charts/ # Chart files
48+
├── content/
49+
│ └── en/ # English content
50+
│ ├── cloud/ # Layer5 Cloud documentation
51+
│ ├── kanvas/ # Kanvas documentation
52+
│ ├── contributing/ # Contribution guidelines
53+
│ └── videos/ # Video content
54+
├── data/ # Hugo data files
55+
├── layouts/ # Hugo templates and layouts
56+
│ ├── _default/ # Default layouts
57+
│ ├── partials/ # Partial templates
58+
│ └── shortcodes/ # Custom shortcodes
59+
├── static/ # Static assets
60+
├── hugo.toml # Hugo configuration
61+
├── package.json # npm dependencies
62+
├── Makefile # Build automation
63+
└── CONTRIBUTING.md # Contribution guidelines
64+
```
65+
66+
## Development Workflow
67+
68+
### Setup
69+
```bash
70+
# Install dependencies (required for fresh clone)
71+
make setup
72+
# or
73+
npm install
74+
```
75+
76+
### Development
77+
```bash
78+
# Start development server with drafts and future content
79+
make site
80+
# or
81+
hugo server -D -F
82+
```
83+
84+
### Building
85+
```bash
86+
# Build for production
87+
make build
88+
# or
89+
hugo
90+
91+
# Clean and rebuild
92+
make clean
93+
```
94+
95+
### Docker Development
96+
```bash
97+
# Run with Docker (requires Docker Desktop 4.24+ or Docker Compose 2.22+)
98+
make docker
99+
```
100+
101+
## Content Guidelines
102+
103+
### Tone and Style
104+
- Use a **professional yet approachable** tone
105+
- Content should be clear, concise, and welcoming to both technical and non-technical audiences
106+
- Align with Layer5's mission of empowering engineers to "expect more from their infrastructure"
107+
- Use American English spelling and grammar
108+
109+
### Markdown Content
110+
- All documentation content is written in Markdown
111+
- Place content files in appropriate directories under `content/en/`
112+
- Include proper frontmatter with metadata:
113+
114+
```yaml
115+
---
116+
title: "Page Title"
117+
description: "Short description for SEO (150-160 chars)"
118+
weight: 10 # Optional: controls ordering in navigation
119+
---
120+
```
121+
122+
### Hugo Shortcodes
123+
Use the project's custom shortcodes for enhanced content:
124+
125+
```markdown
126+
{{< alert type="success" title="Note" >}} Your Note {{< /alert >}}
127+
```
128+
129+
Alert types:
130+
- `type="danger"`: Critical alerts (security-related or breaking changes)
131+
- `type="info"`: General informational content
132+
- `type="warning"`: Important warnings that need attention
133+
- `type="note"`: Neutral notes and tips
134+
- `type="success"`: Positive outcomes or confirmations
135+
136+
### Image Guidelines
137+
- Use the following syntax: `![alt text](/path/to/image.svg)` or `<img src="" alt="" />`
138+
- Always provide complete image paths for subpages
139+
- Add `data-modal="false"` to prevent images from opening in a modal
140+
- Always include descriptive alt text for accessibility and SEO
141+
142+
### Content Restrictions
143+
- **No external images**: Use local assets only
144+
- **No placeholder text**: Provide complete, production-ready content
145+
- **No sensitive data**: Never include API keys, credentials, or personal information
146+
- **Use proper terminology**: "Meshery" not "meshery", "Kanvas" not "canvas", "Layer5" not "layer5"
147+
148+
## Template Guidelines
149+
150+
### Hugo Templates
151+
- Follow Go template syntax conventions
152+
- Use partials for reusable template components
153+
- Maintain consistent indentation in templates
154+
- Use Hugo's built-in functions when possible
155+
156+
### Styling
157+
- SCSS files are located in `assets/`
158+
- Follow existing CSS class naming conventions
159+
- Ensure responsive design is maintained
160+
- Use theme variables when possible
161+
162+
## Accessibility
163+
164+
**Required Standards**: WCAG 2.1 Level AA
165+
166+
- **Images**: Always include descriptive `alt` text
167+
- **Interactive elements**: Ensure keyboard navigation support
168+
- **ARIA labels**: Use when semantic HTML is insufficient
169+
- **Color contrast**: Maintain at least 4.5:1 ratio for text
170+
- **Semantic HTML**: Use appropriate HTML5 elements
171+
172+
## Git Workflow
173+
174+
### Commit Messages
175+
Follow Conventional Commits format:
176+
177+
```
178+
<type>(<scope>): <subject>
179+
```
180+
181+
**Types**:
182+
- `feat`: New feature or content
183+
- `fix`: Bug fix or correction
184+
- `docs`: Documentation changes
185+
- `style`: Formatting changes (no logic change)
186+
- `refactor`: Code refactoring
187+
- `chore`: Build process, tooling, dependencies
188+
189+
**Examples**:
190+
```
191+
feat(cloud): add workspace documentation
192+
fix(kanvas): correct broken link in navigation
193+
docs(contributing): update setup instructions
194+
```
195+
196+
### Pull Requests
197+
- Submit all changes as PRs to the `master` branch
198+
- Reference related issues in PR description
199+
- Ensure CI checks pass before requesting review
200+
- Sign-off commits with `git commit -s`
201+
202+
### Branch Naming
203+
Use descriptive, kebab-case names:
204+
- `feat/add-cloud-security-docs`
205+
- `fix/navigation-broken-link`
206+
- `docs/update-contributing-guide`
207+
208+
## Troubleshooting
209+
210+
### Build Errors
211+
- Check `hugo.toml` for configuration issues
212+
- Clear cache: `hugo --cleanDestinationDir`
213+
- Reinstall dependencies: `rm -rf node_modules && npm install`
214+
- Verify Hugo extended version is installed
215+
216+
### Content Issues
217+
- Validate Markdown syntax and frontmatter
218+
- Check for unclosed shortcodes
219+
- Verify file paths are correct and case-sensitive
220+
221+
### Development Server Issues
222+
- Ensure Go is installed (required): `go version`
223+
- Check Node.js version matches `.nvmrc`
224+
- Verify Hugo extended version is installed
225+
226+
## Security Best Practices
227+
228+
- Never commit secrets, API keys, or credentials
229+
- Use environment variables for sensitive configuration
230+
- Keep dependencies up to date
231+
- Follow CSP headers and security configurations
232+
233+
## Community and Resources
234+
235+
### Documentation
236+
- Layer5 Community Handbook: https://layer5.io/community/handbook
237+
- Meshery Documentation: https://docs.meshery.io
238+
- Hugo Documentation: https://gohugo.io/documentation/
239+
240+
### Getting Help
241+
- Layer5 Slack: https://slack.layer5.io
242+
- Discussion Forum: https://discuss.layer5.io
243+
- GitHub Issues: https://github.com/layer5io/docs/issues
244+
245+
### Code of Conduct
246+
All contributions must adhere to the [Layer5 Code of Conduct](CODE_OF_CONDUCT.md).
247+
248+
## Summary Checklist for Contributions
249+
250+
Before submitting a PR, verify:
251+
252+
### Content Quality
253+
- [ ] Content is clear, accurate, and complete
254+
- [ ] Proper frontmatter is included
255+
- [ ] Images have descriptive alt text
256+
- [ ] Links are valid and accessible
257+
- [ ] Terminology is correct (Meshery, Kanvas, Layer5)
258+
- [ ] American English spelling and grammar
259+
260+
### Technical Quality
261+
- [ ] Build completes successfully (`make build`)
262+
- [ ] Site renders correctly locally (`make site`)
263+
- [ ] Changes are minimal and surgical
264+
- [ ] No placeholder content or sensitive data
265+
- [ ] Responsive design is maintained
266+
267+
### Accessibility
268+
- [ ] All images have alt text
269+
- [ ] Proper heading hierarchy
270+
- [ ] Keyboard navigation works
271+
- [ ] Color contrast meets WCAG standards
272+
273+
### Git
274+
- [ ] Commit messages follow Conventional Commits
275+
- [ ] Commits are signed off (`git commit -s`)
276+
- [ ] PR references related issues
277+
278+
## Example Documentation Page
279+
280+
```markdown
281+
---
282+
title: "Getting Started with Layer5 Cloud"
283+
description: "Learn how to set up your Layer5 Cloud account and start managing your cloud native infrastructure with ease."
284+
weight: 1
285+
---
286+
287+
# Getting Started with Layer5 Cloud
288+
289+
This guide walks you through setting up your Layer5 Cloud account and exploring key features.
290+
291+
## Prerequisites
292+
293+
Before you begin, ensure you have:
294+
- A GitHub or Google account for authentication
295+
- Basic familiarity with cloud native concepts
296+
297+
## Creating Your Account
298+
299+
1. Visit [Layer5 Cloud](https://cloud.layer5.io)
300+
2. Click **Sign Up** and choose your authentication method
301+
3. Complete your profile setup
302+
303+
{{< alert type="info" title="Tip" >}}
304+
You can link multiple authentication providers to a single account.
305+
{{< /alert >}}
306+
307+
## Next Steps
308+
309+
- [Explore Workspaces](/cloud/spaces/workspaces/)
310+
- [Learn about Organizations](/cloud/identity/organizations/)
311+
- [Set up API Tokens](/cloud/security/tokens/)
312+
```
313+
314+
This document serves as the primary reference for GitHub Copilot when assisting with contributions to the Layer5 Documentation site. Always prioritize minimal changes, maintain existing patterns, and ensure quality through building and testing.

0 commit comments

Comments
 (0)