mirror of
https://github.com/ublue-os/packages.git
synced 2026-11-03 21:49:48 -09:00
[WIP] ✨ Set up Copilot instructions (#946)
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: castrojo <1264109+castrojo@users.noreply.github.com>
This commit is contained in:
Copilot
GitHub
parent
95fed5ddb0
commit
e81b55f1d7
1 changed files with 200 additions and 0 deletions
200
.github/copilot-instructions.md
vendored
Normal file
200
.github/copilot-instructions.md
vendored
Normal file
|
|
@ -0,0 +1,200 @@
|
|||
# Copilot Instructions for Universal Blue Packages Repository
|
||||
|
||||
## Repository Overview
|
||||
|
||||
This repository contains RPM package specifications and build configurations for Universal Blue projects. Packages are built using mock/rpmbuild and distributed via COPR repositories.
|
||||
|
||||
## Technology Stack
|
||||
|
||||
- **Build System**: RPM/Mock with custom builder container (`ghcr.io/ublue-os/ublue-builder`)
|
||||
- **Task Runner**: Just (justfiles) for automation
|
||||
- **Languages**: Shell scripts, Python spec files, Just recipes
|
||||
- **CI/CD**: GitHub Actions with renovate for dependency updates
|
||||
- **Package Types**: RPM packages (.spec files)
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
.
|
||||
├── packages/ # Main packages for Universal Blue
|
||||
├── staging/ # Experimental/testing packages
|
||||
├── akmods/ # Kernel module packages
|
||||
├── bluefin/ # Bluefin-specific packages
|
||||
├── aurora/ # Aurora-specific packages
|
||||
├── ublue-builder/ # Builder container configuration
|
||||
└── Justfile # Main build automation recipes
|
||||
```
|
||||
|
||||
## Code Style and Conventions
|
||||
|
||||
### RPM Spec Files
|
||||
|
||||
1. **Follow Fedora Packaging Guidelines**: All specs should adhere to [Fedora Packaging Guidelines](https://docs.fedoraproject.org/en-US/packaging-guidelines/)
|
||||
2. **Pass rpmlint**: All packages must pass rpmlint checks (rpkg-based packages are an exception)
|
||||
3. **Version Management**:
|
||||
- Bump `Version:` for upstream software updates in packages with sources in this repo
|
||||
- Bump `Release:` for packaging changes (use `rpmdev-bumpspec` when possible)
|
||||
- Reset `Release` to 1 when bumping `Version`
|
||||
4. **Renovate Support**: Add renovate comments for automatic updates:
|
||||
```spec
|
||||
# renovate: datasource=github-releases depName=owner/repo
|
||||
Version: 1.0.0
|
||||
```
|
||||
5. **Offline Building**: Packages must be buildable offline once sources are fetched
|
||||
6. **Changelog**: Include meaningful changelog entries when bumping versions
|
||||
|
||||
### Just Recipes
|
||||
|
||||
1. **File Naming**: Use `.just` extension for imported recipes
|
||||
2. **Header Format**: Follow the pattern in `packages/ublue-os-just/src/header.just`
|
||||
3. **Syntax Checking**: All justfiles must pass `just check` validation
|
||||
4. **Comments**: Document complex recipes with comments explaining purpose and parameters
|
||||
5. **Shebang**: Use `#!/usr/bin/bash` or `#!/usr/bin/env bash` for shell script blocks
|
||||
|
||||
### Shell Scripts
|
||||
|
||||
1. **Shebang**: Always use `#!/usr/bin/env bash` or `#!/usr/bin/bash`
|
||||
2. **Error Handling**: Use `set -euo pipefail` for strict error handling
|
||||
3. **Quoting**: Always quote variables: `"$VAR"` instead of `$VAR`
|
||||
4. **Functions**: Use snake_case for function names
|
||||
5. **Config Pattern**: Use the `get_config()` pattern seen in ublue-motd and ublue-rebase-helper
|
||||
6. **shellcheck**: Code should pass shellcheck linting
|
||||
|
||||
## Building and Testing
|
||||
|
||||
### Building a Package
|
||||
|
||||
```bash
|
||||
# Build with default Fedora version in builder container
|
||||
just build ./packages/package-name/package-name.spec
|
||||
|
||||
# Build for specific release
|
||||
just build ./packages/package-name/package-name.spec -r fedora-41-$(arch)
|
||||
|
||||
# Build for EPEL
|
||||
just build ./staging/package-name/package-name.spec -r epel-10-$(arch)
|
||||
|
||||
# Cross-compile (requires qemu-user-static on host)
|
||||
just build ./packages/package-name/package-name.spec --forcearch=aarch64
|
||||
```
|
||||
|
||||
### Testing
|
||||
|
||||
1. **Just Syntax**: Run `just check` to validate all justfiles
|
||||
2. **Local Testing**: Create a testing distrobox:
|
||||
```bash
|
||||
distrobox create --name testingbox --image ghcr.io/ublue-os/ublue-builder
|
||||
```
|
||||
3. **Build Artifacts**: Check `mock/` directory for resulting RPMs/SRPMs and build logs
|
||||
|
||||
## Contributing Guidelines
|
||||
|
||||
### New Package Checklist
|
||||
|
||||
- [ ] Follow Fedora Packaging Guidelines
|
||||
- [ ] Pass rpmlint checks
|
||||
- [ ] Buildable offline once sources are fetched
|
||||
- [ ] Renovate can automatically update the package
|
||||
- [ ] Proper versioning and changelog entries
|
||||
- [ ] File issue to add package to appropriate COPR after merge
|
||||
|
||||
### Existing Package Updates
|
||||
|
||||
- [ ] Bump `Version` (for upstream updates) or `Release` (for packaging changes)
|
||||
- [ ] Use `rpmdev-bumpspec` for release bumps when possible
|
||||
- [ ] Include meaningful changelog entries
|
||||
- [ ] Pass all linting checks
|
||||
- [ ] Test build locally before submitting PR
|
||||
|
||||
### Version Bumping Rules
|
||||
|
||||
**Bump Version when:**
|
||||
- Upstream software has a new release
|
||||
- Updating source files in this repository
|
||||
- Example: `Version: 1.0.0` → `Version: 1.1.0`
|
||||
|
||||
**Bump Release when:**
|
||||
- Making packaging-only changes (patches, dependencies, file lists)
|
||||
- No upstream version change
|
||||
- Example: `Release: 1%{?dist}` → `Release: 2%{?dist}`
|
||||
- Use: `rpmdev-bumpspec path/to/package.spec`
|
||||
|
||||
## Security Considerations
|
||||
|
||||
1. **PR Review**: All PRs must be reviewed for RCE exploits and GitHub Actions abuse
|
||||
2. **safe-to-run Label**: Maintainers must add `safe-to-run` label before CI runs
|
||||
3. **No Secrets**: Never commit secrets or credentials to the repository
|
||||
4. **Dependencies**: Verify all external sources and dependencies
|
||||
|
||||
## Common Tasks
|
||||
|
||||
### Adding a New Package
|
||||
|
||||
1. Create package directory in appropriate location (`packages/`, `staging/`, etc.)
|
||||
2. Write the `.spec` file following guidelines
|
||||
3. Add renovate comments for version tracking
|
||||
4. Test build locally: `just build ./path/to/package.spec`
|
||||
5. Submit PR and request maintainer review
|
||||
|
||||
### Updating Package Version
|
||||
|
||||
```bash
|
||||
# For external source packages
|
||||
rpmdev-bumpspec path/to/package.spec
|
||||
|
||||
# For internal source packages
|
||||
# Manually edit Version field in .spec file
|
||||
```
|
||||
|
||||
### Running Renovate Locally
|
||||
|
||||
```bash
|
||||
# Requires renovate installed (via brew or npm)
|
||||
export GITHUB_COM_TOKEN=your_token
|
||||
just renovate
|
||||
```
|
||||
|
||||
## File-Specific Patterns
|
||||
|
||||
### Config Files Pattern (motd, rebase-helper)
|
||||
|
||||
```bash
|
||||
get_config() {
|
||||
CONFIG_FILE="${CONFIG_FILE:-/etc/default/config.json}"
|
||||
QUERY="$1"
|
||||
FALLBACK="$2"
|
||||
OUTPUT="$(jq -r "$QUERY" "$CONFIG_FILE" 2>/dev/null || echo "$FALLBACK")"
|
||||
if [ "$OUTPUT" == "null" ]; then
|
||||
echo "$FALLBACK"
|
||||
return
|
||||
fi
|
||||
echo "$OUTPUT"
|
||||
}
|
||||
```
|
||||
|
||||
### Distrobox Recipes Pattern
|
||||
|
||||
- Use `source /usr/lib/ujust/ujust.sh` for ujust library functions
|
||||
- Implement `Choose` function for interactive selection
|
||||
- Support `prompt` parameter for interactive mode
|
||||
|
||||
## CI/CD Workflows
|
||||
|
||||
- **validate-just.yml**: Checks syntax of all justfiles
|
||||
- **build-package.yml**: Builds changed packages in PRs
|
||||
- **renovate.yml**: Automated dependency updates
|
||||
- **release-please.yml**: Automated releases and changelogs
|
||||
|
||||
## Important Notes
|
||||
|
||||
- Mock builds mount `mock/` directory - results appear there
|
||||
- Builder container image: `ghcr.io/ublue-os/ublue-builder:latest`
|
||||
- System extensions directory: `/var/lib/extensions`
|
||||
- Always disable pagers in git commands: `git --no-pager`
|
||||
|
||||
## Getting Help
|
||||
|
||||
- Documentation: [Universal Blue Just Documentation](https://docs.projectbluefin.io/administration#community-aliases-and-workarounds)
|
||||
- COPR Repositories: https://copr.fedorainfracloud.org/coprs/ublue-os
|
||||
- Issues: File issues on GitHub for questions or problems
|
||||
- Package READMEs: Check `./packages/README.md` for COPR purposes
|
||||
Loading…
Reference in a new issue