Skip to content

Commit

Permalink
Change name in docs to Zokka
Browse files Browse the repository at this point in the history
After some feedback that shouldn't have the word "elm" in it
  • Loading branch information
changlinli committed Dec 5, 2023
1 parent 73b7928 commit d8d5437
Show file tree
Hide file tree
Showing 6 changed files with 106 additions and 106 deletions.
6 changes: 3 additions & 3 deletions CREATING_A_NEW_PACKAGE_FOR_PACKAGE_OVERRIDES.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ Packages used to override other packages should:
1. Be API-compatible with the original package. I.e. use the exact same module
names and function/value names.
2. Be clearly marked as a package to be used to override other packages. E.g. by
convention all the Zelm packages used as overrides are named
convention all the Zokka packages used as overrides are named
`$ORIGINAL_PACKAGE_AUTHOR-$ORIGINAL_PACKAGE_NAME-$ORIGINAL_PACKAGE_MAJOR_MINOR-override`.
3. Not be published on the standard Elm package repository.
4. Not be used as a normal dependency by any other package or application.
Expand All @@ -26,9 +26,9 @@ package if they are used in the same project. Therefore we want to minimize the
chances where someone could end up either directly or indirectly depending on
both a package and another API-identical package meant to override the former.
Packages meant to override other packages should only ever show up in
`zelm-package-overrides`. By keeping package overrides off of the standard Elm
`zokka-package-overrides`. By keeping package overrides off of the standard Elm
repository and clearly labeling such packages as overrides, we prevent
unsuspecting Elm developers who aren't using Zelm from inadvertently ending up
unsuspecting Elm developers who aren't using Zokka from inadvertently ending up
with a project that has uncompilable, conflicting dependencies.

The fifth rule has to do with the nature of dependency resolution. If your
Expand Down
8 changes: 4 additions & 4 deletions DESIGN_CHOICES.md
Original file line number Diff line number Diff line change
@@ -1,19 +1,19 @@
## Compatibility Constraints

Zelm aims to be:
Zokka aims to be:

1. As in `README.md`, bicompatible with the Elm compiler when it comes to a
given piece of Elm 0.19.1 code.
2. Not interfere with the execution of the vanilla Elm compiler, i.e. a user
should be able to switch back and forth arbitrarily between invocations of
`zelm` and `elm` without the need to perform any sort of clean-up operation
`zokka` and `elm` without the need to perform any sort of clean-up operation
in-between, such as deleting `elm-stuff` or `$ELM_HOME`.
3. Be reasonably compatible with existing IDE tooling. We add the caveat
"reasonably," because without any updates to the IDE tools, we cannot ensure
that those tools take dependency overrides into account when providing
features such as "click to definition." However, outside of zelm-specific
features such as "click to definition." However, outside of zokka-specific
features, we should preserve IDE compatibility as much as possible.

This has a variety of downstream effects on technical choices that Zelm has
This has a variety of downstream effects on technical choices that Zokka has
made, as elaborated further in the FAQs.

8 changes: 4 additions & 4 deletions FAQs.md
Original file line number Diff line number Diff line change
@@ -1,18 +1,18 @@

## The design of Zelm
## The design of Zokka

+ Why have a separate `custom-package-repository-config.json` file in
`$ELM_HOME` instead of just extending `elm.json` even more? Zelm aims to be
`$ELM_HOME` instead of just extending `elm.json` even more? Zokka aims to be
compatible with current Elm tooling, especially IDE tooling. Current IDE
integrations assume that there is a global cache of packages located in
`$ELM_HOME` rather than local per-project caches (as is e.g. the case with
`npm`). This means that to play nicely with these tooling choices, Zelm also
`npm`). This means that to play nicely with these tooling choices, Zokka also
reuses the same global cache. However, because the cache is global to
`$ELM_HOME`, while many Elm projects can use the same `$ELM_HOME`, if one project has a
`custom-package-repository-config.json` that declares one location for a
given package while another project declares another location and those two
locations do not have the same code for that package, one project can break
another. This sort of breakage can appear to be non-deterministic to a user
and can be extremely frustrating to debug. To avoid this, we colocate
`custom-package-repository-config.json` with $ELM_HOME.
`custom-package-repository-config.json` with `$ELM_HOME`.
+ More FAQs forthcoming...
38 changes: 19 additions & 19 deletions GOVERNANCE.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
**This is all hypothetical and subject to change. This document is only really
relevant if Zelm gets enough adoption to actually require a governance structure**.
relevant if Zokka gets enough adoption to actually require a governance structure**.

In light of Zelm's tightly scoped technical goals as well as the current state
of Elm's community, Zelm's social dynamics will look different from Elm's.
In light of Zokka's tightly scoped technical goals as well as the current state
of Elm's community, Zokka's social dynamics will look different from Elm's.

In particular Elm's community is:

Expand All @@ -11,21 +11,21 @@ In particular Elm's community is:
+ Relatively consistent when it comes to opinions about what Elm code should
look like:

**And as a reminder Zelm does not intend (at least not until 2025) to do feature
**And as a reminder Zokka does not intend (at least not until 2025) to do feature
development on the Elm language itself or any expansionary feature development
on the Elm compiler.**

This mean that Zelm does not really need a visionary at its helm or large
amounts of time and energy spent on groundbreaking features. What Zelm needs
This mean that Zokka does not really need a visionary at its helm or large
amounts of time and energy spent on groundbreaking features. What Zokka needs
instead foremost is a low, but consistent, amount of attention to accept PRs and
bug reports from the community. Secondarily, as time allows, Zelm will slowly
bug reports from the community. Secondarily, as time allows, Zokka will slowly
grind through bugs that have no PRs.

The absence of a need for radical design or commitment and instead a focus on a
consistent source of low amounts of energy makes Zelm a good fit for committee
consistent source of low amounts of energy makes Zokka a good fit for committee
leadership rather than individual leadership.

As such Zelm hopes to
As such Zokka hopes to

+ Maintain at least five active members of the `zelm` and `zelm-explorations`
GitHub organizations who have push/merge permissions across the repositories
Expand All @@ -36,24 +36,24 @@ As such Zelm hopes to
engage more than once a week) for active members.

**These are hopes not commitments.** But I do consider them valid barometers of
whether Zelm has a project has succeeded.
whether Zokka has a project has succeeded.

Because Zelm does not intend (at least not until 2025) to do feature
development on the Elm language itself, Zelm makes a different set of social
Because Zokka does not intend (at least not until 2025) to do feature
development on the Elm language itself, Zokka makes a different set of social
trade-offs compared to Elm itself.

Concretely, Zelm hopes to achieve timely (< 1 week) responses to issues and PRs
that fit within Zelm's mission scope, i.e. bug fixes to foundational packages or
Concretely, Zokka hopes to achieve timely (< 1 week) responses to issues and PRs
that fit within Zokka's mission scope, i.e. bug fixes to foundational packages or
to the compiler. These should be fixes with very few or no questions of design
and no changes to any APIs.

**Note that responses do not necessarily mean that issues will be fixed or PRs
will be merged**. Again, because of how tightly scoped Zelm's technical mission
is, it is likely that many issues and PRs will lie outside what Zelm intends to
address at least until 2025. Even if the issue or PR lies within Zelm's scope,
will be merged**. Again, because of how tightly scoped Zokka's technical mission
is, it is likely that many issues and PRs will lie outside what Zokka intends to
address at least until 2025. Even if the issue or PR lies within Zokka's scope,
it may either be tricky to fit or to merge in.

However, even if you don't get your issue fixed or merged into a Zelm
repository, Zelm gives you the tools through custom repositories and package
However, even if you don't get your issue fixed or merged into a Zokka
repository, Zokka gives you the tools through custom repositories and package
overrides to do a lot of this on your own!

Loading

0 comments on commit d8d5437

Please sign in to comment.