Site promotion tools
This commit is contained in:
parent
5188145a27
commit
f4d9772bd3
9 changed files with 723 additions and 2 deletions
270
.github/instructions/instructions.instructions.md
vendored
Normal file
270
.github/instructions/instructions.instructions.md
vendored
Normal file
|
|
@ -0,0 +1,270 @@
|
|||
---
|
||||
description: 'Guidelines for creating high-quality custom instruction files for GitHub Copilot'
|
||||
applyTo: '**/*.instructions.md'
|
||||
---
|
||||
|
||||
# Custom Instructions File Guidelines
|
||||
|
||||
Instructions for creating effective and maintainable custom instruction files that guide GitHub Copilot in generating domain-specific code and following project conventions.
|
||||
|
||||
## Project Context
|
||||
|
||||
- Target audience: Developers and GitHub Copilot working with domain-specific code
|
||||
- File format: Markdown with YAML frontmatter
|
||||
- File naming convention: lowercase with hyphens (e.g., `react-best-practices.instructions.md`)
|
||||
- Location: `.github/instructions/` directory
|
||||
- Purpose: Provide context-aware guidance for code generation, review, and documentation
|
||||
|
||||
## Required Frontmatter
|
||||
|
||||
Every instruction file must include YAML frontmatter with the following fields:
|
||||
|
||||
```yaml
|
||||
---
|
||||
description: 'Brief description of the instruction purpose and scope'
|
||||
applyTo: 'glob pattern for target files (e.g., **/*.ts, **/*.py)'
|
||||
---
|
||||
```
|
||||
|
||||
### Frontmatter Guidelines
|
||||
|
||||
- **description**: Single-quoted string, 1-500 characters, clearly stating the purpose
|
||||
- **applyTo**: Glob pattern(s) specifying which files these instructions apply to
|
||||
- Single pattern: `'**/*.ts'`
|
||||
- Multiple patterns: `'**/*.ts, **/*.tsx, **/*.js'`
|
||||
- Specific files: `'src/**/*.py'`
|
||||
- All files: `'**'`
|
||||
|
||||
## File Structure
|
||||
|
||||
A well-structured instruction file should include the following sections:
|
||||
|
||||
### 1. Title and Overview
|
||||
|
||||
- Clear, descriptive title using `#` heading
|
||||
- Brief introduction explaining the purpose and scope
|
||||
- Optional: Project context section with key technologies and versions
|
||||
|
||||
### 2. Core Sections
|
||||
|
||||
Organize content into logical sections based on the domain:
|
||||
|
||||
- **General Instructions**: High-level guidelines and principles
|
||||
- **Best Practices**: Recommended patterns and approaches
|
||||
- **Code Standards**: Naming conventions, formatting, style rules
|
||||
- **Architecture/Structure**: Project organization and design patterns
|
||||
- **Common Patterns**: Frequently used implementations
|
||||
- **Security**: Security considerations (if applicable)
|
||||
- **Performance**: Optimization guidelines (if applicable)
|
||||
- **Testing**: Testing standards and approaches (if applicable)
|
||||
|
||||
### 3. Examples and Code Snippets
|
||||
|
||||
Provide concrete examples with clear labels:
|
||||
|
||||
```markdown
|
||||
### Good Example
|
||||
\`\`\`language
|
||||
// Recommended approach
|
||||
code example here
|
||||
\`\`\`
|
||||
|
||||
### Bad Example
|
||||
\`\`\`language
|
||||
// Avoid this pattern
|
||||
code example here
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
### 4. Validation and Verification (Optional but Recommended)
|
||||
|
||||
- Build commands to verify code
|
||||
- Linting and formatting tools
|
||||
- Testing requirements
|
||||
- Verification steps
|
||||
|
||||
## Content Guidelines
|
||||
|
||||
### Writing Style
|
||||
|
||||
- Use clear, concise language
|
||||
- Write in imperative mood ("Use", "Implement", "Avoid")
|
||||
- Be specific and actionable
|
||||
- Avoid ambiguous terms like "should", "might", "possibly"
|
||||
- Use bullet points and lists for readability
|
||||
- Keep sections focused and scannable
|
||||
|
||||
### Best Practices
|
||||
|
||||
- **Be Specific**: Provide concrete examples rather than abstract concepts
|
||||
- **Show Why**: Explain the reasoning behind recommendations when it adds value
|
||||
- **Use Tables**: For comparing options, listing rules, or showing patterns
|
||||
- **Include Examples**: Real code snippets are more effective than descriptions
|
||||
- **Stay Current**: Reference current versions and best practices
|
||||
- **Link Resources**: Include official documentation and authoritative sources
|
||||
|
||||
### Instruction Altitude (Goldilocks Zone)
|
||||
|
||||
- Start with the minimum rule set that fully defines expected outcomes
|
||||
- Add constraints after observed failures, not hypothetical edge cases
|
||||
- Prefer high-signal examples over exhaustive decision tables
|
||||
|
||||
| Altitude | Failure Mode | Result |
|
||||
| --- | --- | --- |
|
||||
| Over-specified | Brittle if-else prose | Breaks on unlisted cases |
|
||||
| Under-specified | Assumes shared context | Generic outputs |
|
||||
| Right altitude | Heuristics + examples | Stable, generalizable quality |
|
||||
|
||||
### Common Patterns to Include
|
||||
|
||||
1. **Naming Conventions**: How to name variables, functions, classes, files
|
||||
2. **Code Organization**: File structure, module organization, import order
|
||||
3. **Error Handling**: Preferred error handling patterns
|
||||
4. **Dependencies**: How to manage and document dependencies
|
||||
5. **Comments and Documentation**: When and how to document code
|
||||
6. **Version Information**: Target language/framework versions
|
||||
|
||||
## Patterns to Follow
|
||||
|
||||
### Bullet Points and Lists
|
||||
|
||||
```markdown
|
||||
## Security Best Practices
|
||||
|
||||
- Always validate user input before processing
|
||||
- Use parameterized queries to prevent SQL injection
|
||||
- Store secrets in environment variables, never in code
|
||||
- Implement proper authentication and authorization
|
||||
- Enable HTTPS for all production endpoints
|
||||
```
|
||||
|
||||
### Tables for Structured Information
|
||||
|
||||
```markdown
|
||||
## Common Issues
|
||||
|
||||
| Issue | Solution | Example |
|
||||
| ---------------- | ------------------- | ----------------------------- |
|
||||
| Magic numbers | Use named constants | `const MAX_RETRIES = 3` |
|
||||
| Deep nesting | Extract functions | Refactor nested if statements |
|
||||
| Hardcoded values | Use configuration | Store API URLs in config |
|
||||
```
|
||||
|
||||
### Code Comparison
|
||||
|
||||
```markdown
|
||||
### Good Example - Using TypeScript interfaces
|
||||
\`\`\`typescript
|
||||
interface User {
|
||||
id: string;
|
||||
name: string;
|
||||
email: string;
|
||||
}
|
||||
|
||||
function getUser(id: string): User {
|
||||
// Implementation
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
### Bad Example - Using any type
|
||||
\`\`\`typescript
|
||||
function getUser(id: any): any {
|
||||
// Loses type safety
|
||||
}
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
### Conditional Guidance
|
||||
|
||||
```markdown
|
||||
## Framework Selection
|
||||
|
||||
- **For small projects**: Use Minimal API approach
|
||||
- **For large projects**: Use controller-based architecture with clear separation
|
||||
- **For microservices**: Consider domain-driven design patterns
|
||||
```
|
||||
|
||||
## Patterns to Avoid
|
||||
|
||||
- **Overly verbose explanations**: Keep it concise and scannable
|
||||
- **Outdated information**: Always reference current versions and practices
|
||||
- **Ambiguous guidelines**: Be specific about what to do or avoid
|
||||
- **Missing examples**: Abstract rules without concrete code examples
|
||||
- **Contradictory advice**: Ensure consistency throughout the file
|
||||
- **Copy-paste from documentation**: Add value by distilling and contextualizing
|
||||
- **Hypothetical-rule inflation**: Do not add rules for failures that have not occurred
|
||||
|
||||
## Testing Your Instructions
|
||||
|
||||
Before finalizing instruction files:
|
||||
|
||||
1. **Test with Copilot**: Try the instructions with actual prompts in VS Code
|
||||
2. **Verify Examples**: Ensure code examples are correct and run without errors
|
||||
3. **Check Glob Patterns**: Confirm `applyTo` patterns match intended files
|
||||
|
||||
## Example Structure
|
||||
|
||||
Here's a minimal example structure for a new instruction file:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: 'Brief description of purpose'
|
||||
applyTo: '**/*.ext'
|
||||
---
|
||||
|
||||
# Technology Name Development
|
||||
|
||||
Brief introduction and context.
|
||||
|
||||
## General Instructions
|
||||
|
||||
- High-level guideline 1
|
||||
- High-level guideline 2
|
||||
|
||||
## Best Practices
|
||||
|
||||
- Specific practice 1
|
||||
- Specific practice 2
|
||||
|
||||
## Code Standards
|
||||
|
||||
### Naming Conventions
|
||||
- Rule 1
|
||||
- Rule 2
|
||||
|
||||
### File Organization
|
||||
- Structure 1
|
||||
- Structure 2
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Pattern 1
|
||||
Description and example
|
||||
|
||||
\`\`\`language
|
||||
code example
|
||||
\`\`\`
|
||||
|
||||
### Pattern 2
|
||||
Description and example
|
||||
|
||||
## Validation
|
||||
|
||||
- Build command: `command to verify`
|
||||
- Linting: `command to lint`
|
||||
- Testing: `command to test`
|
||||
```
|
||||
|
||||
## Maintenance
|
||||
|
||||
- Review instructions when dependencies or frameworks are updated
|
||||
- Update examples to reflect current best practices
|
||||
- Remove outdated patterns or deprecated features
|
||||
- Add new patterns as they emerge in the community
|
||||
- Keep glob patterns accurate as project structure evolves
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Custom Instructions Documentation](https://code.visualstudio.com/docs/copilot/customization/custom-instructions)
|
||||
- [Awesome Copilot Instructions](https://github.com/github/awesome-copilot/tree/main/instructions)
|
||||
- [System Prompt Altitude — Effective Context Engineering for AI Agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents#the-anatomy-of-effective-context)
|
||||
131
.github/instructions/regalamiunsorriso-83-149-164-4.instructions.md
vendored
Normal file
131
.github/instructions/regalamiunsorriso-83-149-164-4.instructions.md
vendored
Normal file
|
|
@ -0,0 +1,131 @@
|
|||
---
|
||||
description: 'Use when: deploying, staging, copying, or promoting regalamiunsorriso site files on server 83.149.164.4, especially for sync/** and www/** changes.'
|
||||
applyTo: 'sync/**, www/**'
|
||||
---
|
||||
|
||||
# Regalami Un Sorriso Server 83.149.164.4
|
||||
|
||||
Instructions in this file are specific to the `regalamiunsorriso` site hosted on server `83.149.164.4` over SSH port `410`.
|
||||
|
||||
## Server Access
|
||||
|
||||
- SSH user: `marco`
|
||||
- SSH key: `C:\Users\Maddo\.ssh\id_rsa`
|
||||
- SSH port: `410`
|
||||
- Direct SSH login works with the key above.
|
||||
- The login banner before authentication is expected.
|
||||
|
||||
## Preferred SSH Workflow
|
||||
|
||||
Use an interactive TTY when a command may need sudo:
|
||||
|
||||
```powershell
|
||||
ssh -tt -i C:\Users\Maddo\.ssh\id_rsa -p 410 marco@83.149.164.4
|
||||
```
|
||||
|
||||
For root access, use:
|
||||
|
||||
```tcsh
|
||||
sudo tcsh
|
||||
```
|
||||
|
||||
If you need a single elevated command:
|
||||
|
||||
```powershell
|
||||
ssh -tt -i C:\Users\Maddo\.ssh\id_rsa -p 410 marco@83.149.164.4 "sudo tcsh -c 'command here'"
|
||||
```
|
||||
|
||||
## Shell Behavior On This Host
|
||||
|
||||
- The remote login shell behaves as `tcsh`.
|
||||
- POSIX shell constructs like `for ...; do ...; done` fail unless you explicitly run them through `sh -c`.
|
||||
- The server `sh` does not support `-l`, so use `sh -c`, not `sh -lc`.
|
||||
- If `sudo` reports that a terminal is required, reconnect with `-tt`.
|
||||
|
||||
## MCP Limitation
|
||||
|
||||
- The MCP SSH tools have not been reliable for this host and previously failed authentication or transport checks.
|
||||
- Prefer direct terminal SSH commands for this server unless the MCP path is revalidated.
|
||||
|
||||
## Site Paths
|
||||
|
||||
- Incoming staging root: `/home/marco/regalamiunsorriso/incoming/www`
|
||||
- Live site root: `/home/sites/regalamiunsorriso/www`
|
||||
|
||||
## Staging Workflow
|
||||
|
||||
When `www/**` files need deployment:
|
||||
|
||||
1. Build the file list from git changes after the initial `www` import baseline.
|
||||
2. Include any required uncommitted working tree files explicitly if they must be deployed.
|
||||
3. Copy the selected files into `/home/marco/regalamiunsorriso/incoming/www`, preserving the `www/...` directory structure.
|
||||
4. Prefer a streamed tar transfer over SSH for batches of files.
|
||||
|
||||
Example staging command pattern:
|
||||
|
||||
```powershell
|
||||
tar -cf - -C K:\various\regalamiunsorriso <file-list-under-www> | ssh -i C:\Users\Maddo\.ssh\id_rsa -p 410 marco@83.149.164.4 "tar -xf - -C /home/marco/regalamiunsorriso/incoming"
|
||||
```
|
||||
|
||||
## Promotion Rules
|
||||
|
||||
- Promotion to the live site must happen through `sudo tcsh`.
|
||||
- Do not copy directly as `marco` into `/home/sites/regalamiunsorriso/www`.
|
||||
- Before replacing an existing live file, capture its exact owner, group, and mode.
|
||||
- After copy, restore the same owner, group, and mode exactly.
|
||||
- For new files, use the permissions of surrounding live files of the same type in the same directory.
|
||||
- If same-extension files in the directory have mixed modes, choose an explicit metadata source file and reuse its owner, group, and mode.
|
||||
|
||||
## Promotion Automation
|
||||
|
||||
Use these scripts for this site:
|
||||
|
||||
- Local helper: `sync/promote-file.sh`
|
||||
- Local batch helper: `sync/promote-www-remaining.sh`
|
||||
- Remote helper: `/home/marco/promote-file.sh`
|
||||
- Remote batch helper: `/home/marco/promote-www-remaining.sh`
|
||||
|
||||
### Single File Promotion
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
ssh -tt -i C:\Users\Maddo\.ssh\id_rsa -p 410 marco@83.149.164.4 "sudo tcsh -c '/home/marco/promote-file.sh <staged-path> <live-path> [metadata-source]'"
|
||||
```
|
||||
|
||||
Behavior of `promote-file.sh`:
|
||||
|
||||
- If the destination already exists, it copies the file and restores that destination file's original owner, group, and mode.
|
||||
- If the destination does not exist, it can use an optional third argument as the metadata source file.
|
||||
- If no third argument is provided for a new file, it falls back to sampling sibling files in the destination directory.
|
||||
|
||||
### New PHP Files In Live Root
|
||||
|
||||
Root-level PHP files on this site do not all share one mode.
|
||||
|
||||
- `/home/sites/regalamiunsorriso/www/_inc_footer.php` is `jenkins:www` with mode `775`
|
||||
- `/home/sites/regalamiunsorriso/www/gallery1.php` is `jenkins:www` with mode `775`
|
||||
- `/home/sites/regalamiunsorriso/www/test.php` is `jenkins:www` with mode `644`
|
||||
|
||||
For the `faceai_*.php` files, use `/home/sites/regalamiunsorriso/www/_inc_footer.php` as the explicit metadata source.
|
||||
|
||||
## Verification
|
||||
|
||||
After staging or promotion, verify with:
|
||||
|
||||
- `ls -l` for owner, group, and visible mode
|
||||
- `stat -f` for exact metadata
|
||||
- `cksum` to compare staged and live file contents
|
||||
|
||||
Run verification commands separately if a parallel terminal run becomes unreliable.
|
||||
|
||||
## Documentation Expectations
|
||||
|
||||
When performing deployments or promotions for this site:
|
||||
|
||||
- Record the list of changed files being deployed.
|
||||
- Distinguish updated files from new files.
|
||||
- Note whether any deployed file came from the working tree instead of a commit.
|
||||
- Document every shell quirk or command failure encountered.
|
||||
- Document the metadata source used for any new live file.
|
||||
- Update `sync/www-deploy-manifest.md` when the deployment set or procedure changes.
|
||||
Loading…
Add table
Add a link
Reference in a new issue