Skip to content

Commit d3bb80e

Browse files
vincentvanbushvincentvanbush
committed
Update README and add conduct and contributing docs
1 parent 999e107 commit d3bb80e

3 files changed

Lines changed: 280 additions & 6 deletions

File tree

‎CODE_OF_CONDUCT.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Code of Conduct
2+
3+
Contact: [contact@curiosum.com][0]
4+
5+
## Contributing to the Permit ecosystem
6+
7+
In discussions and development regarding the project, the [Code of Conduct][0] applies for all of the [Permit][1], [Permit.Ecto][2], [Permit.Phoenix][3], [Permit.Absinthe][4] repositories as well as their communication channels, including GitHub issues and discussions as well as the [Elixir Slack channel][5].
8+
9+
[0]: mailto:contact@curiosum.com?subject=Permit:%20Code%20of%20Conduct%20Report
10+
[1]: https://github.com/curiosum_dev/permit/
11+
[2]: https://github.com/curiosum_dev/permit_ecto/
12+
[3]: https://github.com/curiosum_dev/permit_phoenix/
13+
[4]: https://github.com/curiosum_dev/permit_absinthe/
14+
[5]: https://elixir-lang.slack.com/archives/C091Q5S0GDU

‎CONTRIBUTING.md‎

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
# Contributing to Permit.Ecto
2+
3+
Thank you for your interest in contributing to Permit.Ecto! This document provides guidelines and information for contributors.
4+
5+
## Code of Conduct
6+
7+
This project adheres to a [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.
8+
9+
## Getting started
10+
11+
### Development environment
12+
13+
#### Prerequisites
14+
15+
* Elixir 1.12+ and OTP 24+
16+
- _If implementing a proposed feature requires bumping Elixir or OTP, we're open to considering that._
17+
* Git
18+
* **PostgreSQL** - Required for running tests and development of Ecto-dependent features
19+
20+
Developing and testing the `permit_ecto` package requires a running Postgres instance as this package provides database integration for Permit's authorization system.
21+
22+
#### Setup
23+
24+
1. Clone the repository and install dependencies:
25+
```bash
26+
git clone https://github.com/curiosum-dev/permit_ecto.git
27+
cd permit_ecto
28+
mix deps.get
29+
```
30+
31+
2. Set up your test database (configure in `config/test.exs`):
32+
```bash
33+
MIX_ENV=test mix do ecto.create, ecto.migrate
34+
```
35+
36+
3. Run tests to ensure everything is working:
37+
```bash
38+
mix test
39+
```
40+
41+
When running Credo and Dialyzer, please use `MIX_ENV=test` to ensure tests and support files are validated, too.
42+
43+
## How to contribute
44+
45+
### Before proceeding: where to discuss things?
46+
47+
The best place to discuss fresh ideas for the library's future and ask any sorts of questions (not strictly constituting an issue as defined below) is the [Permit channel in Elixir's Slack workspace][0]. You can also use the appropriate [GitHub Discussions][1] channel. We're usually easiest approachable via Slack, though 😉
48+
49+
For example, if you've got a general question about Permit.Ecto's development direction, or about its intended behaviour in a specific scenario, it's more convenient to open up a discussion on Slack (or use GitHub discussions) than to file an issue right away.
50+
51+
However, if there's clearly a bug you'd like to report, or you have a specific feature idea that you'd like to explain, it's perfect material for a GitHub issue inside the project!
52+
53+
### Reporting issues
54+
55+
Before creating an issue, please:
56+
57+
1. **Search existing issues** to avoid duplicates
58+
2. **Use the issue templates** when available
59+
3. **For bug reports, provide detailed information**:
60+
- Elixir/OTP versions
61+
- Permit.Ecto version
62+
- Ecto and Postgres versions
63+
- Minimal reproduction case
64+
- Expected vs actual behavior
65+
4. **For feature requests, check against roadmap outlined in [main Permit README](https://github.com/curiosum-dev/permit/blob/master/README.md) and provide the following**:
66+
- Purpose of the new feature
67+
- Intended usage syntax (or pseudocode)
68+
- Expected implementation complexity (if possible to gauge)
69+
- Expected impact on other existing features and backward compatibility
70+
- How it relates to Ecto query generation and authorization scoping
71+
72+
### Pull requests
73+
74+
#### Before you start
75+
76+
- **Check existing PRs** to avoid duplicate work
77+
- **Open an issue** for discussion on significant changes (we follow the 1 issue <-> 1 PR principle)
78+
- **Follow our coding standards** (see below)
79+
80+
#### PR process
81+
82+
1. **Fork the repository** and create a feature branch
83+
2. **Make your changes** with clear, focused commits
84+
3. **Add tests** for new functionality
85+
4. **Update documentation** as needed, including README
86+
5. **Run the full test suite** as well as all static checks
87+
6. **Submit your PR** with a clear description
88+
89+
#### PR Requirements
90+
91+
- [ ] Code compiles without warnings (`mix compile --warnings-as-errors`)
92+
- [ ] Tests pass (`mix test`)
93+
- _Includes added tests to new features and fixed bugs._
94+
- _Tests pass for all combinations of tool versions covered by the CI matrix (see `.github/workflows/elixir.yml`)._
95+
- [ ] Code follows style guidelines (`MIX_ENV=test mix credo`)
96+
- _Run Credo in test environment to ensure tests and support code adheres to style rules as well._
97+
- [ ] Types are correct (`MIX_ENV=test mix dialyzer`)
98+
- _Run Credo in test environment to ensure tests and support code has correct typing as well._
99+
- _Precise typing is encouraged for all newly added modules and functions._
100+
- _Ignores are permitted with an inline comment with proper justification._
101+
- [ ] Documentation is updated: a bare minimum is updates to affected public API parts
102+
- _Functions intended for usage by application code must have descriptions of arguments, purpose, and usage examples._
103+
- _For crucial additions to features, README must also be updated._
104+
- [ ] Database tests include proper cleanup and isolation
105+
- [ ] Commit messages are clear and descriptive
106+
- If already used throughout commit history, use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
107+
- Otherwise, use single-line messages formatted as: `Commit purpose in imperative mode [#issue_number]`.
108+
- Focus on what vs how, and keep it simple
109+
- Example: `Fix incorrect query generation for has_many associations [#123]`
110+
111+
## Development guidelines
112+
113+
### Code style
114+
115+
We use [Credo](https://github.com/rrrene/credo) for code analysis:
116+
117+
```bash
118+
MIX_ENV=test mix credo
119+
```
120+
121+
Key principles:
122+
- **Clarity over cleverness** - write readable code and avoid introducing new DSLs as much as possible. Permit.Ecto focuses on clean Ecto query generation from authorization rules. Prefer pure Elixir for easier debugging and code clarity. Use macros wisely and only when needed.
123+
* **Minimal dependencies** - Permit.Ecto should only rely on what's needed for its Ecto integration scope. Core Permit functionality belongs in the main `permit` package, while Phoenix-specific features belong in `permit_phoenix`.
124+
- **Follow Elixir conventions** - use standard patterns and don't fight the platform. Avoid [common Elixir anti-patterns](https://hexdocs.pm/elixir/what-anti-patterns.html). Write functional, idiomatic Elixir code.
125+
- **Follow Ecto conventions** - use Ecto query patterns appropriately, handle dynamic queries safely, and ensure proper query composition.
126+
- **Avoid RDBMS-specific features** - whenever possible, implement features in a way that's independent on whether Postgres, MySQL or any other DB is used.
127+
- **Document public APIs** - include `@doc` and `@moduledoc` written as if you were the one who is to read them. Avoid `@moduledoc false` unless a module is deeply private. As long as typing in Elixir relies on Dialyzer, do type with `@spec` extensively, use `Permit.Types` and `Permit.Ecto.Types` wherever applicable, and avoid typing with the likes of `map()`, `any()`, or `term()` where possible.
128+
- **Handle errors gracefully** - always consider what's the correct scheme of error propagation. There is no globally assumed convention of whether to use error tuples or exceptions, you should use whatever feels appropriate and in line with adjacent elements of the system.
129+
130+
### Testing
131+
132+
- **Write tests for all new functionality and bug fixes**
133+
- **Maintain high test coverage**
134+
- **Use descriptive test names**
135+
- **Test both success and failure cases**
136+
- **Test query generation correctness** - ensure generated Ecto queries match expected authorization scoping
137+
- **Test association handling** - verify proper query generation for has_one, has_many, and belongs_to relationships
138+
- **Clean up test data** - use correct setup to ensure tests don't leave side effects in the database
139+
140+
### Commit messages
141+
142+
Follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) format if already used in the repository. Otherwise, write single-line messages in imperative mode and mark related issue number with [#number].
143+
144+
### Branching strategy
145+
146+
Follow [Conventional Branch](https://conventional-branch.github.io/) format if already used in the repository. Otherwise, use `issue_number-issue_name` as branch names. Create feature branches off `main` or `master` and avoid a nested branch tree.
147+
148+
## Release process
149+
150+
Releases are handled by maintainers:
151+
152+
1. Version bump in `mix.exs`
153+
2. Update `CHANGELOG.md`
154+
3. Create GitHub release
155+
4. Publish to Hex.pm
156+
157+
## Community
158+
159+
### Getting help
160+
161+
- [Elixir Slack channel][0] - for chat, questions and general discussion
162+
- [GitHub Discussions][1] - for questions and general discussion
163+
- [GitHub Issues][2] - for bug reports and feature requests
164+
- [Curiosum Blog][3] - for updates, tutorials and other content
165+
166+
### Recognition
167+
168+
We are eager to publicly recognize your valuable input as a Permit.Ecto contributor! Your contributions will be highlighted in subsequent release notes, as well as blog posts announcing community contributions.
169+
170+
## Questions?
171+
172+
Feel free to:
173+
- Ping us on [Elixir Slack][0]
174+
- Open a [GitHub Discussion](https://github.com/curiosum-dev/permit/discussions)
175+
- Contact us at [Curiosum](https://curiosum.com/contact)
176+
- Check our [blog](https://curiosum.com/blog) for updates
177+
178+
Thank you for contributing to Permit.Ecto! 🎉
179+
180+
[0]: https://elixir-lang.slack.com/archives/C091Q5S0GDU
181+
[1]: https://github.com/curiosum-dev/permit/discussions
182+
[2]: https://github.com/curiosum-dev/permit_ecto/issues
183+
[3]: https://curiosum.com/blog?search=permit

‎README.md‎

Lines changed: 83 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,38 @@
1-
# Permit.Ecto
1+
<div align="center">
2+
<img src="https://github.com/user-attachments/assets/f0352656-397d-4d90-999a-d3adbae1095f">
3+
4+
# Permit.Ecto
5+
<p><strong>Ecto integration for Permit - Convert permissions to Ecto queries with automatic authorization scoping.
6+
</strong></p>
7+
8+
[![Contact Us](https://img.shields.io/badge/Contact%20Us-%23F36D2E?style=for-the-badge&logo=maildotru&logoColor=white&labelColor=F36D2E)](https://curiosum.com/contact)
9+
[![Visit Curiosum](https://img.shields.io/badge/Visit%20Curiosum-%236819E6?style=for-the-badge&logo=elixir&logoColor=white&labelColor=6819E6)](https://curiosum.com/services/elixir-software-development)
10+
[![License: MIT](https://img.shields.io/badge/License-MIT-1D0642?style=for-the-badge&logo=open-source-initiative&logoColor=white&labelColor=1D0642)]()
11+
</div>
12+
13+
14+
<br/>
15+
16+
## Purpose and usage
17+
18+
Permit.Ecto integrates [`Permit`](https://github.com/curiosum-dev/permit) with Ecto, providing means to convert permissions to Ecto queries and automatically constructing `Ecto.Query` scopes to preload records that meet authorization criteria.
19+
20+
Key features:
21+
- **Automatic query generation** - Convert Permit permissions into Ecto queries
22+
- **Authorization scoping** - Automatically scope database queries based on user permissions
23+
- **Association support** - Handle has_one, has_many, and belongs_to relationships in permission rules
24+
- **Seamless integration** - Works with Permit.Phoenix for automatic controller and LiveView authorization
225

326
[![Hex version badge](https://img.shields.io/hexpm/v/permit_ecto.svg)](https://hex.pm/packages/permit_ecto)
427
[![Actions Status](https://github.com/curiosum-dev/permit_ecto/actions/workflows/elixir.yml/badge.svg)](https://github.com/curiosum-dev/permit_ecto/actions)
528
[![Code coverage badge](https://img.shields.io/codecov/c/github/curiosum-dev/permit_ecto/master.svg)](https://codecov.io/gh/curiosum-dev/permit_ecto/branch/master)
629
[![License badge](https://img.shields.io/hexpm/l/permit_ecto.svg)](https://github.com/curiosum-dev/permit_ecto/blob/master/LICENSE.md)
730

8-
Integrates [`Permit`](https://github.com/curiosum-dev/permit) with Ecto, providing means to convert permissions to Ecto queries, automatically constructing `Ecto.Query` scopes to preload records that meet authorization criteria.
9-
1031
## Dependencies and related libraries
1132

1233
`Permit.Ecto` depends on `Permit`. It can be used to build custom integrations or in conjunction with `Permit.Phoenix`, which uses the generated `accessible_by/4` functions to automatically preload, authorize and inject records loaded via Ecto into controller assigns (see more in [`Permit.Phoenix documentation`](https://github.com/curiosum-dev/permit_phoenix)).
1334

14-
## Configuration
35+
## Usage
1536

1637
```elixir
1738
defmodule MyApp.Authorization do
@@ -63,6 +84,33 @@ iex> MyApp.Permissions.accessible_by!(%MyApp.Users.User{id: 3, role: :admin}, :u
6384
[%MyApp.Blog.Article{id: 1, ...}, %MyApp.Blog.Article{id: 2, ...}, %MyApp.Blog.Article{id: 3, ...}]
6485
```
6586

87+
### Quick authorization checks
88+
89+
Generate Ecto queries based on permissions for direct database querying:
90+
91+
```elixir
92+
# Generate query scoped to user permissions
93+
query = MyApp.Authorization.accessible_by!(current_user, :read, Article)
94+
articles = MyApp.Repo.all(query)
95+
96+
# Use with pagination and other Ecto features
97+
query
98+
|> where([a], a.published == true)
99+
|> order_by([a], desc: a.inserted_at)
100+
|> limit(10)
101+
|> MyApp.Repo.all()
102+
```
103+
104+
## Ecosystem
105+
106+
Permit.Ecto is part of the modular Permit ecosystem:
107+
108+
| Package | Version | Description |
109+
|---------|---------|-------------|
110+
| **[permit](https://hex.pm/packages/permit)** | [![Hex.pm](https://img.shields.io/hexpm/v/permit.svg)](https://hex.pm/packages/permit) | Core authorization library |
111+
| **[permit_ecto](https://hex.pm/packages/permit_ecto)** | [![Hex.pm](https://img.shields.io/hexpm/v/permit_ecto.svg)](https://hex.pm/packages/permit_ecto) | Ecto integration for database queries |
112+
| **[permit_phoenix](https://hex.pm/packages/permit_phoenix)** | [![Hex.pm](https://img.shields.io/hexpm/v/permit_phoenix.svg)](https://hex.pm/packages/permit_phoenix) | Phoenix Controllers & LiveView integration |
113+
| **[permit_absinthe](https://github.com/curiosum-dev/permit_absinthe)** | [![Hex.pm](https://img.shields.io/hexpm/v/permit_absinthe.svg)](https://hex.pm/packages/permit_absinthe) | GraphQL API authorization via Absinthe |
66114

67115
## Installation
68116

@@ -71,10 +119,39 @@ The package can be installed by adding `permit_ecto` to your list of dependencie
71119
```elixir
72120
def deps do
73121
[
74-
{:permit_ecto, "~> 0.2.4"}
122+
{:permit, "~> 0.3.0"}, # Core authorization library
123+
{:permit_ecto, "~> 0.2.4"} # Ecto integration
75124
]
76125
end
77126
```
78127

79-
The docs can be found at <https://hexdocs.pm/permit_ecto>.
128+
For a complete setup with Phoenix or Absinthe integration, add `:permit_phoenix` or `:permit_absinthe`.
129+
130+
## Documentation
131+
132+
- **Permit.Ecto docs**: [hexdocs.pm/permit_ecto](https://hexdocs.pm/permit_ecto)
133+
- **Core library**: [hexdocs.pm/permit](https://hexdocs.pm/permit)
134+
135+
## Contributing
136+
137+
We welcome contributions! Please see our [Contributing Guide](https://github.com/curiosum-dev/permit_ecto/blob/master/CONTRIBUTING.md) for details.
138+
139+
### Development setup
140+
141+
Just clone the repository, install dependencies normally, develop and run tests. When running Credo and Dialyzer, please use `MIX_ENV=test` to ensure tests and support files are validated, too.
142+
143+
### Community
144+
145+
- **Slack channel**: [Elixir Slack / #permit](https://elixir-lang.slack.com/archives/C091Q5S0GDU)
146+
- **Issues**: [GitHub Issues](https://github.com/curiosum-dev/permit_ecto/issues)
147+
- **Discussions**: [GitHub Discussions](https://github.com/curiosum-dev/permit/discussions)
148+
- **Blog**: [Curiosum Blog](https://curiosum.com/blog?search=permit)
149+
150+
## Contact
151+
152+
* Library maintainer: [Michał Buszkiewicz](https://github.com/vincentvanbush)
153+
* [**Curiosum**](https://curiosum.com) - Elixir development team behind Permit
154+
155+
## License
80156

157+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

0 commit comments

Comments
 (0)