Cosmos-sdk: File Tags for Code Comprehensibility

[rigelrozanski]

@tnachen and I were talking about the code base as a whole and what is required for it to become more easily understood. One problem is that there is simply _a lot_ of code, if you don't know where to begin it can be difficult to simply pick-up and go. A proposed strategy to help here is the development of file tags.

File Tags

Here, file tags refers to the ability for code to be ordered within multiple categories. Initially the following categories/order is proposed:

• Code priority levels
  
  
  
  • Critical (affects fundamental security of the blockchain)
  
  
  • Part-Critical (affects security but critical-level safeguards are in place to mitigate impact if this code was to be broken)
  
  
  • Non-Critical (Does not affect security of the blockchain)
  
  
• Code kind
  
  
  
  • Client side code
  
  
  • State-machine code
  
  

Specifically, tags should be categorized on a per-file basis and stored in a yaml file somewhere within the repo. A simple CLI tool could be developed to:

• search for an individual file and list its tags
• list files for a directory
  
  
  
  • either alphabetically (with all tag information) or by tag
  
  
  • either recursive or non-recursively
  
  

Issue Tagging

Similarly, the same CLI utility could use the github api to query for issues relating to a particular file, if some new form of "affected file" tagging convention is used within an issue. This new form of tagging would probably look something like including the text "[affected files: x/staking/...]" in the issue description. But I don't know maybe issue tagging is overkill here haha.

---

Ultimately, this file tagging system:

• can help inform new developers of where to start reading
• could help inform the release process as to state machine breaking changes
• be integrated with CI to ensure that code files are not left out or left behind (during renames) from the file tagging system
• be integrated with CI to comment on a PR with a report card of which kinds of code changes are being made (state-machine critical for instance)

CC @alexanderbez @fedekunze @jordansexton @AdityaSripal @colin-axner

[alexanderbez]

Very neat idea. How do we propose to do this? Annotations in file names? What if files contain a mixture of "tags" -- both priority and code kind? This also sounds like something we should tackle in a piecemeal manner.

[rigelrozanski]

Yeah I like the idea of including the tags _right in_ each file. Should be pretty easy to include these tags right in the file as a comment near the package definition. Maybe something like:

// FILETAGS: priority=critical; kind=state-machine

[AdityaSripal]

I like this idea! On a somewhat related note, I'd like to organize the CHANGELOG in a similar manner. Breaking Changes is too broad in my opinion since there are different types of breaking changes that are more or less relevant to users. I propose splitting the Breaking Changes into subsections

Client Breaking Changes

# breaking cli commands or REST routes
# Useful for users building wallets, explorers, etc. 
Also useful for users of specific Cosmos-SDK Blockchains (e.g. Gaia users).
Not relevant for developers using the SDK but building their own client.

API Breaking Changes:

# breaking the API of any SDK functions
# Most useful for developers building their blockchains on SDK. 
Not relevant for end-users (e.g. transactors on Gaia)

State-Machine Breaking Changes:

# breaks the state machine (new feature will cause different apphash given the same set of tx's)
# Probably relevant for everyone, except perhaps developers who have not launched their blockchain yet.

If a feature can exist in multiple subsections, it should be replicated in all relevant subsections so that users of the SDK can just read the sections pertinent to their usecase.

I proposed something similar to this in Gaia but didn't get around to implementing, if there's support for it here then i can put up a quick PR for both SDK and Gaia tomorrow.

[tnachen]

@AdityaSripal +1 this is what we used to do for Mesos and other open source projects, to clearly communicate breaking changes. Another is also upgrade related notes if there are specific steps you need to take too.

[rigelrozanski]

@AdityaSripal I think this is a reasonably good idea. I'm into it. However it will obviously implemented in a totally different way than file tags

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.