122 lines
2.9 KiB
Markdown
122 lines
2.9 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
|
|
├── index.js, index.d.ts # npm package loader (@crudy/pgmorbac)
|
|
├── 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, package.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 Gitea release (Drone does this on the
|
|
tag when the repository is activated there):
|
|
|
|
```bash
|
|
PGMORBAC_RELEASE_KEY=<path to the Ed25519 key> GITEA_URL=https://git.villains.fr \
|
|
GITEA_REPO=crudy/pgmorbac GITEA_TOKEN=<token> npm run release
|
|
```
|
|
|
|
6. npm package `@crudy/pgmorbac` (the SQL is built from `src/` on prepack). Publish
|
|
the same version to the local Verdaccio, for crudy development, and to npmjs:
|
|
|
|
```bash
|
|
npm publish --registry http://localhost:4873
|
|
npm publish --registry https://registry.npmjs.org
|
|
```
|
|
|
|
## 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).
|