Naming Conventions and Deprecation Policy - LibertyDSNP/frequency GitHub Wiki
Rust
Hard Rules
Indexed Code
SCALE encoding and a lot of the metadata relies on stable indices. When adding any of the prior, do NOT reorder. ALWAYS add to the end. Those relying on those magic numbers thank you.
- Pallet Indexes
- Events
- Extrinsics
- Argument order
External Interface Stability Required
Remember that more is external than it might appear.
- State Queries
- Constants
- Runtime Calls
- Custom RPCs
Changes MUST follow the deprecation pattern.
Deprecation Policy
Changes will happen and eventual deprecation of something is expected. Any change that alters an external interface MUST follow the following if at all possible.
- Create a new interface, if necessary, suffix the name(s) with
_v2
(or correct integer increment). - In Rust, tag the prior interface as
#[deprecated = "Use xxxx_v2 instead"]
- Note in the Changelog the deprecation.
- Wait at least 6 months.
- Remove the deprecated interface noting the "BREAKING CHANGE" in the
CHANGELOG
as per Conventional Commits guidelines.
e.g.
BREAKING CHANGE: a commit that has a footer BREAKING CHANGE:, or appends a ! after the type/scope, introduces a breaking API change (correlating with [MAJOR](http://semver.org/#summary) in Semantic Versioning). A BREAKING CHANGE can be part of commits of any type.
Suggestions
General Rules of Thumb
- Avoid single words on external interfaces
- Governance managed variables should be prefaced by
governance
- Be descriptive
is
/has
: Should return abool
State Storage Values
- Single Maps
- [map key]To[map value]
- [map value]For[map key]
- Double Maps
- [map key]And[map key 2]To[map value]
- N Maps
- Good Luck
Constants
- [Max/Min][Foo]Per[Bar]
Extrinsics
- Verbs
set
: Change a value to a new valueadd
: Append to a list of somethingcreate
: Creating something new that might have other things added to itregister
: USEcreate
INSTEADgrant/revoke
: Permission oriented termsdelete
: Never about permissions, actually delete somethingretire
: Delete is not right, but neither is revoke (Used for MSAs "removal" only)
- Junctions
with
by
- Help
- Foo
grants/revokes
apermission
- A
delegator
creates a delegation with aprovider
- A user
creates
an MSA and thenadds
public keys to it.
- Foo
RPCs
getBy
: pallet_getByFoocheck
: Test a thing and return result- No need to prefix with
get
Events
- Past tense verbs