[DONE] Proposal: Rename IOTA DID types

[m-renaud]

Proposal Summary

Rename IOTA-specific DID types to contain an Iota prefix, and update filenames to match.

Status

Implemented: #219 #243

Motivation

There are currently a proliferation of types in the identity.rs package with the same name, but in different directories and crates, with unique semantics and validation logic (DID, Document, and Method to name a few). This makes understanding the codebase more difficult because one constantly needs to check which version of the type is being use'd in a given file. As a smaller matter, the re-use of the same filename multiple times makes navigating the codebase in an editor more challenging, forcing you to always double check the path.

Proposal

Summary

• Prefix "core" DID types with the Core prefix (eg. Document -> CoreDocument)
• Prefix IOTA-specific DID types with the Iota prefix (eg. DID -> IotaDID)
• Rename IOTA-specific files to contain an iota_ prefix (eg. did.rs -> iota_did.rs)
• Prefix wasm types with Wasm prefix (eg. DID -> WasmDID)
• Rename wasm-specific files to contain a wasm_ prefix (eg. did.rs -> wasm_did.rs)
• (optional) Rename files that have ambiguous names (eg. document.rs -> diff_document.rs)

Details

In this section we list the full set of renames to perform:

Completed in #219

• identity-did/src/document/document.rs -> identity-did/src/document/core_document.rs
  • Document -> CoreDocument
• identity-did/src/verification/method.rs -> identity-did/src/verification/verification_method.rs
  • Method -> VerificationMethod
• identity-iota/src/did/doc/document.rs -> identity-iota/src/did/doc/iota_document.rs
  • Document -> IotaDocument
• identity-iota/src/did/doc/method.rs -> identity-iota/src/did/doc/iota_method.rs
  • Method -> IotaMethod
• identity-iota/src/did/url/did.rs -> identity-iota/src/did/url/iota_did.rs
  • DID -> IotaDID
• bindings/wasm/src/document.rs -> bindings/wasm/src/wasm_document.rs
  • Document -> WasmDocument
• bindings/wasm/src/method.rs -> bindings/wasm/src/wasm_method.rs
  • Method -> WasmMethod
• bindings/wasm/src/did.rs -> bindings/wasm/src/wasm_did.rs
  • DID -> WasmDID

Optional (file rename only, reduces the number of times you open the wrong document.rs :P)

Completed in #243

• identity-iota/src/chain/document.rs -> identity-iota/src/chain/document_chain.rs
  • DocumentChain (no change)
• identity-iota/src/chain/diff.rs -> identity-iota/src/chain/diff_chain.rs
  • DiffChain (no change)
• identity-iota/src/did/doc/diff.rs -> identity-iota/src/did/doc/document_diff.rs
  • DocumentDiff (no change)
• identity-did/src/diff/document.rs -> identity-did/src/diff/diff_document.rs
  • DiffDocument (no change)
• identity-did/src/diff/method.rs -> identity-did/src/diff/diff_method.rs
  • DiffMethod (no change)
• identity-did/src/diff/service.rs -> identity-did/src/diff/diff_service.rs
  • DiffService (no change)
• identity-did/src/diff/did_key.rs -> identity-did/src/diff/did_key_diff.rs
  • Contains Diff impl for DIDKey (no change)

When should we do this?

We have three options for when to do this:

• (1) Never: Leave things as they are. This will result in continued confusion for newcomers to the code base.
• (2) Before the Beta release: There is a planned beta release of the library in a few weeks. If we make these changes before that release release we avoid any churn for users of the library in the future.
• (3) After the Beta release: Waiting until after the release buys us more time to consider exactly what we want to rename, but at the cost of churn for users of the library when upgrading to the next version.

In both options (2) and (3) there will be churn for anyone who currently has a PR in progress or local branches.

Preferences

(2): @m-renaud @l1h3r

Timeline

If we agree on (2), we should make these changes in the next ~2-3 weeks.

If we agree on (3), we can revisit in the future.

NOTE: A temporary moratorium on PRs would help reduce repeated rebases/merges.

Who?

I (@m-renaud) can own these changes.

Changelog

Any changes to the proposal as a result of discussions will be reflected here. When the proposal is finalized we can create an issue to track the changes and point back to this discussion.

• April 20th: Initial draft
• April 21st: Add core and wasm type renames (per @l1h3r's comments), inline @l1h3r's preference for (2)

[m-renaud]

@JelleMillenaar @Aconitin @l1h3r PTAL!

[l1h3r]

@m-renaud thanks for doing this!

Some thoughts

• There would also be a set of Wasm-prefixed types in bindings/wasm
• I think it's better to also rename the "core" types. The commonly used types will be Iota-prefixed

I would prefer option (2) - way better for users and shouldn't be too much overhead for the WIP PRs

[JelleMillenaar]

About the Wasm prefix. How will we scale that? We will also have C-Document and Python-Document. Not sure if I like that. Overall I am a big supported of increasing the clarity this way :)

[l1h3r]

C bindings will just use pointers to the existing Iota- types (eg. *const IotaDocument) so no new types there.

There could be a PyDocument type but I guess this depends on how those bindings are built. I was hoping we could use the C bindings to avoid creating multiple rust interfaces though (same for Java bindings..)

[l1h3r]

About the Wasm prefix. How will we scale that?

This is already a scalability issue if we have to maintain that many "custom" document types 😛

We will also have C-Document and Python-Document. Not sure if I like that

They can still be exposed as Document in their respective languages if that's what you don't like?

[m-renaud]

Are there any changes you'd like to see in #219 per this convo thread?

[l1h3r]

Just one thing below - this thread can probably be split off into a new discussion about the design of future bindings.

They can still be exposed as Document in their respective languages

I don't think it makes much sense to use WasmDID from JavaScript since you don't have access to the underlying rust types. We can keep the explicit rust renaming and expose the wasm-specific types without the prefix. I'll leave a comment in the PR about this though (it's just a wasm-bindgen attribute).

[m-renaud]

One more question: should I change IotaMethod to IotaVerificationMethod?

[l1h3r]

I like the shorter names but since we're renaming to be more explicit this makes sense; WasmMethod can also become WasmVerificationMethod.

[m-renaud]

Done.