clj-commons / clj-commons/aleph

Reconsider `:aleph/`-namespaced keywords

Open
#700 3 comments 0 reactions 0 assignees View on GitHub
Dominant language
Clojure
Stars
2.6k
Forks
242
Avg merge
4d 5h
Merged PRs (30d)
1

Description

# Problem

Keywords with an `:aleph/` namespace are currently used inconsistently: Sometimes the namespace means that the keys are internal (e.g. `:aleph/channel`), sometimes they are intended for public use and only namespaced to prevent clashes with other keys in the same map (e.g. [`:aleph/request-arrived`](https://github.com/clj-commons/aleph/pull/275)).

See https://github.com/clj-commons/aleph/pull/699#discussion_r1403507539 and https://github.com/clj-commons/aleph/pull/699#discussion_r1403545356 for prior discussion which lead to the creation of this issue.

# Solution

Still to be determined. One idea we had was to use a different namespace for keys which are indeed not intended for public use (e.g. `:aleph.internal/`).

Also, we should document `:aleph/` keys which are indeed intended for public use.

Contributor guide

Open the contributing guide

Research direction

Review the existing :aleph/ keywords and the discussions in pull requests #275 and #699, including the linked review comments. Decide which names are public and which are internal, establish a consistent namespace convention, and document the public keys; completion requires agreement on the convention and corresponding updates.

Written by the indexing model from the issue text.

Assessment

Tech stack
clojure
Domain
api, documentation
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.