Skip to content

Commit

Permalink
Clarify guidelines
Browse files Browse the repository at this point in the history
Clarify that according to the General README these are guidelines *not* rules, and as such may be overridden with sufficient justification.
  • Loading branch information
rayegun authored Nov 25, 2024
1 parent 83e1363 commit 2f63540
Showing 1 changed file with 6 additions and 4 deletions.
10 changes: 6 additions & 4 deletions docs/src/creating-packages.md
Original file line number Diff line number Diff line change
Expand Up @@ -562,10 +562,10 @@ duplicated into `[extras]`. This is an unfortunate duplication, but without
doing this the project verifier under older Julia versions will throw an error
if it finds packages under `[compat]` that is not listed in `[extras]`.

## Package naming rules
## Package naming guidelines

Package names should be sensible to most Julia users, *even to those who are not domain experts*.
The following rules apply to the `General` registry but may be useful for other package
The following guidelines apply to the `General` registry but may be useful for other package
registries as well.

Since the `General` registry belongs to the entire community, people may have opinions about
Expand All @@ -575,8 +575,10 @@ may fit your package better.

1. Avoid jargon. In particular, avoid acronyms unless there is minimal possibility of confusion.

* It's ok to say `USA` if you're talking about the USA.
* It's not ok to say `PMA`, even if you're talking about positive mental attitude.
* It's ok for package names to contain `DNA` if you're talking about the DNA, which has a universally agreed upon definition.
* It's more difficult to justify package names containing the acronym `CI` for instance, which may mean continuous integration, confidence interval, etc.
* If there is risk of confusion it may be best to disambiguate an acronym with additional words such as a lab group or field.
* If your acronym is unambiguous, easily searchable, and/or unlikely to be confused across domains a good justification is often enough for approval.
2. Avoid using `Julia` in your package name or prefixing it with `Ju`.

* It is usually clear from context and to your users that the package is a Julia package.
Expand Down

0 comments on commit 2f63540

Please sign in to comment.