marc
3e8380d4f7
The signed distribution is published as a GitHub release by the release workflow on v* tags, replacing the Gitea release and its Drone pipeline. The release body and the dist README take the homepage from META.json.
117 lines
2.7 KiB
Markdown
117 lines
2.7 KiB
Markdown
# Development Guide
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
pgmorbac/
|
|
├── src/ # Modular SQL source files
|
|
├── tests/ # Test files
|
|
├── tools/ # Build and test scripts
|
|
├── docs/ # Documentation
|
|
├── pgmorbac.control # Version source of truth
|
|
├── pgmorbac.sql # Generated (git-ignored)
|
|
└── Makefile # Build automation
|
|
```
|
|
|
|
## Version Management
|
|
|
|
Version is defined in `pgmorbac.control` under `default_version`.
|
|
|
|
Edit source files in `src/` and commit them. Never edit or commit `pgmorbac.sql` (generated by build script).
|
|
|
|
## Development Workflow
|
|
|
|
### Edit Source Files
|
|
|
|
```bash
|
|
vim src/authorization.sql
|
|
```
|
|
|
|
### Build and Test
|
|
|
|
```bash
|
|
make check
|
|
```
|
|
|
|
This builds from `src/`, creates a temporary database, runs all tests, and cleans up.
|
|
|
|
### Commit Changes
|
|
|
|
```bash
|
|
git add src/authorization.sql tests/01_authorization.sql
|
|
git commit -m "Add feature X"
|
|
```
|
|
|
|
The build script concatenates `src/` files in dependency order (header first, footer last).
|
|
|
|
## Manual Testing
|
|
|
|
```bash
|
|
make build
|
|
createdb mytest
|
|
psql -d mytest -f pgmorbac.sql
|
|
psql -d mytest
|
|
dropdb mytest
|
|
```
|
|
|
|
## Release Process
|
|
|
|
1. `./tools/bump_version.sh X.Y.Z` (control file, META.json, README)
|
|
2. Update `CHANGELOG.md`
|
|
3. Run `make build` and `make check`
|
|
4. Commit and tag:
|
|
|
|
```bash
|
|
git commit -am "release: X.Y.Z"
|
|
git tag vX.Y.Z
|
|
git push origin master --tags
|
|
```
|
|
|
|
5. Signed SQL distribution, attached to the GitHub release. The `release`
|
|
workflow does this on the tag, signing with the `PGMORBAC_RELEASE_KEY`
|
|
repository secret. By hand:
|
|
|
|
```bash
|
|
PGMORBAC_RELEASE_KEY=<path to the Ed25519 key> GITHUB_REPOSITORY=crudylabs/pgmorbac \
|
|
GITHUB_TOKEN=<token> npm run release
|
|
```
|
|
|
|
6. The npm package `@crudy/pgmorbac` is released from the `pgmorbac-node`
|
|
repository, which packs the SQL of this signed release.
|
|
|
|
## Makefile Targets
|
|
|
|
```bash
|
|
make build # Build from src/ files
|
|
make check # Build and run tests
|
|
make install # Install to PostgreSQL
|
|
make help # Show all targets
|
|
```
|
|
|
|
## Code Style
|
|
|
|
SQL keywords in UPPERCASE. Identifiers in lowercase_snake_case. Always qualify with `morbac.` schema.
|
|
|
|
Functions use `verb_noun` pattern. Tables use plural nouns.
|
|
|
|
## Adding Features
|
|
|
|
1. Edit files in `src/`
|
|
2. Add tests in `tests/`
|
|
3. Update `docs/DOCUMENTATION.md`
|
|
4. Run `make check`
|
|
5. Commit source files
|
|
|
|
## Debugging
|
|
|
|
```sql
|
|
SELECT * FROM morbac.auth_cache ORDER BY computed_at DESC LIMIT 10;
|
|
SELECT morbac.invalidate_cache();
|
|
EXPLAIN ANALYZE SELECT morbac.is_allowed(...);
|
|
SELECT morbac.refresh_hierarchy_cache();
|
|
```
|
|
|
|
## Resources
|
|
|
|
See [DOCUMENTATION.md](DOCUMENTATION.md), [PERFORMANCE.md](PERFORMANCE.md), and [ADMIN_GUIDE.md](ADMIN_GUIDE.md).
|