docs: update zellij-ps to reflect project switcher functionality
- Update package description and fix mainProgram typo - Rewrite documentation to describe project switching, not process viewing - Add PROJECT_FOLDERS configuration and usage examples - Update all references across docs (README, guides, module overviews)
This commit is contained in:
m3tm3re
360
docs/CONTRIBUTING.md
Normal file
360
docs/CONTRIBUTING.md
Normal file
@@ -0,0 +1,360 @@
|
||||
# Contributing
|
||||
|
||||
Contributing to m3ta-nixpkgs.
|
||||
|
||||
## Setting Up Development Environment
|
||||
|
||||
```bash
|
||||
# Clone repository
|
||||
git clone https://code.m3ta.dev/m3tam3re/nixpkgs.git
|
||||
cd nixpkgs
|
||||
|
||||
# Enter development shell (includes linting tools)
|
||||
nix develop
|
||||
|
||||
# Or use a specific shell
|
||||
nix develop .#python
|
||||
nix develop .#devops
|
||||
```
|
||||
|
||||
## Code Style and Formatting
|
||||
|
||||
### Formatting
|
||||
|
||||
Use alejandra to format Nix files:
|
||||
|
||||
```bash
|
||||
# Format all files
|
||||
nix fmt
|
||||
|
||||
# Format specific file
|
||||
alejandra path/to/file.nix
|
||||
```
|
||||
|
||||
**Always run `nix fmt` before committing.**
|
||||
|
||||
### Linting
|
||||
|
||||
Linting tools are only available inside the dev shell:
|
||||
|
||||
```bash
|
||||
# Enter dev shell first
|
||||
nix develop
|
||||
|
||||
# Run statix (linter)
|
||||
statix check .
|
||||
|
||||
# Run deadnix (find dead code)
|
||||
deadnix .
|
||||
```
|
||||
|
||||
## Conventions
|
||||
|
||||
### Naming
|
||||
|
||||
- **Packages**: `lowercase-hyphen` (e.g., `hyprpaper-random`)
|
||||
- **Variables**: `camelCase` (e.g., `portHelpers`)
|
||||
- **Module options**: `m3ta.*` namespace
|
||||
- **Files**: `lowercase-hyphen` (e.g., `my-module.nix`)
|
||||
|
||||
### Imports
|
||||
|
||||
Multi-line, trailing commas:
|
||||
|
||||
```nix
|
||||
{
|
||||
lib,
|
||||
stdenv,
|
||||
fetchFromGitHub,
|
||||
}:
|
||||
```
|
||||
|
||||
### Meta Fields
|
||||
|
||||
Always include all fields in package definitions:
|
||||
|
||||
```nix
|
||||
meta = with lib; {
|
||||
description = "Short description";
|
||||
homepage = "https://github.com/author/repo";
|
||||
license = licenses.mit;
|
||||
platforms = platforms.linux;
|
||||
mainProgram = "program-name";
|
||||
};
|
||||
```
|
||||
|
||||
### Module Pattern
|
||||
|
||||
Standard module pattern:
|
||||
|
||||
```nix
|
||||
{ config, lib, pkgs, ... }:
|
||||
with lib; let
|
||||
cfg = config.m3ta.myModule;
|
||||
in {
|
||||
options.m3ta.myModule = {
|
||||
enable = mkEnableOption "description";
|
||||
};
|
||||
|
||||
config = mkIf cfg.enable {
|
||||
# Configuration
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
## Adding a Package
|
||||
|
||||
1. Create package directory in `pkgs/your-package/`
|
||||
2. Write `default.nix` with package definition
|
||||
3. Register in `pkgs/default.nix`
|
||||
|
||||
See [Adding Packages Guide](./guides/adding-packages.md) for detailed instructions.
|
||||
|
||||
### Package Testing
|
||||
|
||||
```bash
|
||||
# Build the package
|
||||
nix build .#your-package
|
||||
|
||||
# Test if package runs
|
||||
nix run .#your-package -- --help
|
||||
|
||||
# Check with linter
|
||||
nix develop
|
||||
statix check pkgs/your-package/
|
||||
```
|
||||
|
||||
## Adding a NixOS Module
|
||||
|
||||
1. Create module file in `modules/nixos/your-module.nix`
|
||||
2. Import in `modules/nixos/default.nix` (or use directly)
|
||||
|
||||
```nix
|
||||
# modules/nixos/default.nix
|
||||
{
|
||||
imports = [
|
||||
./your-module.nix
|
||||
./other-module.nix
|
||||
];
|
||||
}
|
||||
```
|
||||
|
||||
## Adding a Home Manager Module
|
||||
|
||||
1. Choose appropriate category: `cli/`, `coding/`, or root
|
||||
2. Create module file
|
||||
3. Import in category's `default.nix` or root `default.nix`
|
||||
|
||||
```nix
|
||||
# modules/home-manager/cli/default.nix
|
||||
{
|
||||
imports = [
|
||||
./your-tool.nix
|
||||
];
|
||||
}
|
||||
```
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Making Changes
|
||||
|
||||
```bash
|
||||
# Create feature branch
|
||||
git checkout -b feature/your-change
|
||||
|
||||
# Make changes
|
||||
|
||||
# Format code
|
||||
nix fmt
|
||||
|
||||
# Test builds
|
||||
nix build .#your-package
|
||||
nix flake check
|
||||
|
||||
# Lint
|
||||
nix develop
|
||||
statix check .
|
||||
deadnix .
|
||||
```
|
||||
|
||||
### Commit Format
|
||||
|
||||
Use conventional commits:
|
||||
|
||||
```
|
||||
type: brief description
|
||||
|
||||
Types:
|
||||
- feat: New feature
|
||||
- fix: Bug fix
|
||||
- docs: Documentation changes
|
||||
- style: Code style changes (formatting)
|
||||
- refactor: Code refactoring
|
||||
- chore: Maintenance tasks
|
||||
- test: Adding or updating tests
|
||||
```
|
||||
|
||||
Examples:
|
||||
|
||||
```
|
||||
feat: add new package for myapp
|
||||
fix: resolve port conflict in mem0 module
|
||||
docs: update installation instructions
|
||||
style: format nix files
|
||||
refactor: simplify port management
|
||||
chore: update dependencies
|
||||
```
|
||||
|
||||
### Before Committing
|
||||
|
||||
```bash
|
||||
# Format all files
|
||||
nix fmt
|
||||
|
||||
# Validate flake
|
||||
nix flake check
|
||||
|
||||
# Run linters
|
||||
nix develop
|
||||
statix check .
|
||||
deadnix .
|
||||
|
||||
# Add files
|
||||
git add .
|
||||
|
||||
# Commit
|
||||
git commit -m "type: description"
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
### Package Testing
|
||||
|
||||
```bash
|
||||
# Build for specific system
|
||||
nix build .#your-package --system x86_64-linux
|
||||
|
||||
# Test on different systems
|
||||
nix build .#your-package --system aarch64-linux
|
||||
```
|
||||
|
||||
### Module Testing
|
||||
|
||||
```bash
|
||||
# Test NixOS configuration
|
||||
sudo nixos-rebuild test --flake .#hostname
|
||||
|
||||
# Test Home Manager configuration
|
||||
home-manager switch --flake .#username@hostname
|
||||
```
|
||||
|
||||
### Flake Validation
|
||||
|
||||
```bash
|
||||
# Validate all outputs
|
||||
nix flake check
|
||||
|
||||
# Show all outputs
|
||||
nix flake show
|
||||
```
|
||||
|
||||
## Pull Requests
|
||||
|
||||
### Before Submitting
|
||||
|
||||
1. [ ] Code formatted with `nix fmt`
|
||||
2. [ ] Passes `statix check .`
|
||||
3. [ ] Passes `deadnix .`
|
||||
4. [ ] Passes `nix flake check`
|
||||
5. [ ] New packages include `meta` fields
|
||||
6. [ ] Documentation updated if needed
|
||||
7. [ ] Commit messages follow convention
|
||||
|
||||
### PR Description
|
||||
|
||||
Include:
|
||||
- What changed and why
|
||||
- How to test
|
||||
- Any breaking changes
|
||||
- Related issues
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Hash Errors
|
||||
|
||||
When building packages, you may encounter hash errors:
|
||||
|
||||
```
|
||||
got: sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
|
||||
expected: sha256-BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=
|
||||
```
|
||||
|
||||
**Solution**: Copy the `got` hash and update the package:
|
||||
|
||||
```nix
|
||||
src = fetchFromGitHub {
|
||||
# ...
|
||||
hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="; # Use actual hash
|
||||
};
|
||||
```
|
||||
|
||||
### Dependency Not Found
|
||||
|
||||
If a package isn't found, check:
|
||||
1. Package registered in `pkgs/default.nix`
|
||||
2. Overlay applied in your configuration
|
||||
3. System matches supported platform
|
||||
|
||||
### Linting Errors
|
||||
|
||||
```bash
|
||||
# Fix statix issues manually or use auto-fix where available
|
||||
statix fix .
|
||||
|
||||
# Review deadnix suggestions
|
||||
deadnix -e .
|
||||
```
|
||||
|
||||
## Getting Help
|
||||
|
||||
- Check existing packages and modules for patterns
|
||||
- Read [Architecture](./ARCHITECTURE.md) for design decisions
|
||||
- Review [Code Patterns](./reference/patterns.md) for conventions
|
||||
- Open an issue for questions
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
| Don't | Do Instead |
|
||||
|-------|------------|
|
||||
| `lib.fakeHash` in commits | Get real hash: `nix build`, copy from error |
|
||||
| Flat module files | Organize by category (`cli/`, `coding/`) |
|
||||
| Hardcode ports | Use `m3ta.ports` module |
|
||||
| Skip meta fields | Include all: description, homepage, license, platforms, mainProgram |
|
||||
| `with pkgs;` in modules | Explicit `pkgs.package` or `with pkgs; [ ... ]` in lists only |
|
||||
| Suppress type errors | Fix underlying type issues |
|
||||
| Delete tests to "pass" | Fix failing tests |
|
||||
|
||||
## Code Review Checklist
|
||||
|
||||
- [ ] Follows naming conventions
|
||||
- [ ] Properly formatted (`nix fmt`)
|
||||
- [ ] Passes linting (`statix`, `deadnix`)
|
||||
- [ ] Has complete `meta` fields (packages)
|
||||
- [ ] Documentation updated if needed
|
||||
- [ ] No dead code
|
||||
- [ ] No obvious bugs or issues
|
||||
- [ ] Appropriate for scope
|
||||
|
||||
## Release Process
|
||||
|
||||
This is a personal repository, but semantic versioning is followed for tags:
|
||||
|
||||
1. Update versions as needed
|
||||
2. Update changelog
|
||||
3. Tag release
|
||||
4. Push tags
|
||||
|
||||
```bash
|
||||
git tag -a v1.0.0 -m "Release v1.0.0"
|
||||
git push origin v1.0.0
|
||||
```
|
||||
Reference in New Issue
Block a user