Design philosophy going forward #39

New issue

Closed

opened 2026-05-19 17:53:38 -05:00 by PPPDUD · 2 comments

PPPDUD commented

2026-05-19 17:53:38 -05:00

(Migrated from github.com)

When to change something in Sparkle

You should only change Sparkle's source code in the following scenarios:

you are implementing a new feature
you are correcting a bug that affects the end-user or developers negatively in some way
you are relicensing a file
you are reverting a change

Changing code comments is not acceptable unless it's for the purposes of relicensing, or correcting something that is obviously incorrect or contains invalid English. Adding new ones to better-document the source code is allowed, but when possible it should be included as part of a larger change.

You should not fix things that aren't broken.

Scope of Sparkle

Sparkle is an addon manager for Snap! and its forks. In order to get addons to play nice together, Sparkle needs to provide a few high-level APIs; examples include:

a system for alerting addons when they are about to be deleted (cleanupFunc)
a system to let addons run code when an unrelated function is executed (wrapFunction)
a system to permit users to configure addons using a uniform user interface (options)
and a system to figure out what variant of Snap! the user is currently using (requireSnaps/disallowSnaps/suggestSnaps)

These APIs are provided so that addons have fairly-uniform behavior that's unlikely to cause conflicts, instead of each addon reinventing the wheel in a slightly-different shape, as it would have gone otherwise.

New addon APIs should not be implemented unless any of the following conditions are met:

without the API(s) in question, addon developers will most likely fail to converge on a standard implementation for a feature, leading to conflicts or race conditions
without the API(s) in question, addon developers would have to undergo an unreasonable or infeasible amount of effort to produce their own implementations

Examples of APIs that do not satisfy these conditions include the this.api.inform() function (essentially a small wrapper on top of this.ide.inform()) and this.api.showMsg() (clone of this.ide.showMessage()). ~~It's unclear whether or not this.api.storage.* meets the criteria, so I'm going to give it a special exception for now.~~ this.api.storage.* prevents conflicts between addons and will therefore be kept for the forseeable future.

In the following months, I plan on eliminating these redundant APIs and updating addons to use the new, Snap!-native alternatives.

@codingisfun2831t @Bubgamer07 @e016 While commenting on #38, I realized that we don't have any actual design philosophy rules to adhere to, so effective immediately, I will expect all contributors to follow these guidelines going forward. If you see anything that could use fixing, please let me know and I'll edit this comment. --- ## When to change something in Sparkle You should only change Sparkle's source code in the following scenarios: - you are implementing a new feature - you are correcting a bug that affects the end-user or developers negatively in some way - you are relicensing a file - you are reverting a change Changing code comments is not acceptable unless it's for the purposes of relicensing, or correcting something that is obviously incorrect or contains invalid English. Adding new ones to better-document the source code is allowed, but when possible it should be included as part of a larger change. You should _not_ fix things that aren't broken. ## Scope of Sparkle Sparkle is an addon manager for Snap! and its forks. In order to get addons to play nice together, Sparkle needs to provide a few high-level APIs; examples include: - a system for alerting addons when they are about to be deleted (`cleanupFunc`) - a system to let addons run code when an unrelated function is executed (`wrapFunction`) - a system to permit users to configure addons using a uniform user interface (`options`) - and a system to figure out what variant of Snap! the user is currently using (`requireSnaps/disallowSnaps/suggestSnaps`) These APIs are provided so that addons have fairly-uniform behavior that's unlikely to cause conflicts, instead of each addon reinventing the wheel in a slightly-different shape, as it would have gone otherwise. New addon APIs should not be implemented unless any of the following conditions are met: - without the API(s) in question, addon developers will most likely fail to converge on a standard implementation for a feature, leading to conflicts or race conditions - without the API(s) in question, addon developers would have to undergo an unreasonable or infeasible amount of effort to produce their own implementations Examples of APIs that do not satisfy these conditions include the `this.api.inform()` function (essentially a small wrapper on top of `this.ide.inform()`) and `this.api.showMsg()` (clone of `this.ide.showMessage()`). ~It's unclear whether or not `this.api.storage.*` meets the criteria, so I'm going to give it a special exception for now.~ `this.api.storage.*` prevents conflicts between addons and will therefore be kept for the forseeable future. In the following months, I plan on eliminating these redundant APIs and updating addons to use the new, Snap!-native alternatives.

codingisfun2831t commented

2026-05-19 17:58:55 -05:00

(Migrated from github.com)

storage functions I think are fine. They prevent mod conflicts (prefixed with {id}_). However back when I were first developing Snap!Mods I added those functions as a little API functions since there wasn't much else.

`storage` functions I think are fine. They prevent mod conflicts (prefixed with `{id}_`). However back when I were first developing Snap!Mods I added those functions as a little API functions since there wasn't much else.

PPPDUD commented

2026-05-19 17:59:24 -05:00

(Migrated from github.com)

storage functions I think are fine. They prevent mod conflicts (prefixed with {id}_). However back when I were first developing Snap!Mods I added those functions as a little API functions since there wasn't much else.

Makes sense, I'll update the comment now; thanks!

> `storage` functions I think are fine. They prevent mod conflicts (prefixed with `{id}_`). However back when I were first developing Snap!Mods I added those functions as a little API functions since there wasn't much else. Makes sense, I'll update the comment now; thanks!