docs(core): add core documentation and principles (#21511)

Co-authored-by: Aaron Craelius <aaronc@users.noreply.github.com>

core/appmodule/README.md

@@ -1,7 +0,0 @@
-# Appmodule
-
-<!-- TODO add more docs here with https://github.com/cosmos/cosmos-sdk/issues/17207 -->
-
-This package defines what is needed for an module to be used in the Cosmos SDK. 
-
-If you are looking at integrating Dependency injection into your module please see [depinject appconfig documentation](../../depinject/appconfig/README.md)

core/appmodule/doc.go

@@ -1,5 +1,4 @@
-// Package appmodule defines the functionality for registering Cosmos SDK app
-// modules that are assembled using the cosmossdk.io/depinject
-// dependency injection system and the declarative app configuration format
-// handled by the appconfig package.
+// Package appmodule defines what is needed for an module to be used in the Cosmos SDK (runtime).
+// It is equivalent to the appmodulev2 package, but less flexible to stay compatible with baseapp instead of server/v2.
+// If you are looking at integrating dependency injection into your module please see depinject appconfig documentation.
 package appmodule

core/appmodule/environment.go

@@ -1,9 +1,9 @@
 package appmodule
 
 import (
-	"cosmossdk.io/core/appmodule/v2"
+	appmodulev2 "cosmossdk.io/core/appmodule/v2"
 )
 
-// Environment is used to get all services to their respective module
-// Contract: All fields of environment are always populated.
-type Environment = appmodule.Environment
+// Environment is used to get all services to their respective module.
+// Contract: All fields of environment are always populated by runtime.
+type Environment = appmodulev2.Environment

core/appmodule/genesis.go

@@ -5,7 +5,7 @@ import (
 	"encoding/json"
 	"io"
 
-	"cosmossdk.io/core/appmodule/v2"
+	appmodulev2 "cosmossdk.io/core/appmodule/v2"
 )
 
 // HasGenesisBasics is the legacy interface for stateless genesis methods.
@@ -15,18 +15,18 @@ type HasGenesisBasics interface {
 }
 
 // HasGenesis defines a custom genesis handling API implementation.
-type HasGenesis = appmodule.HasGenesis
+type HasGenesis = appmodulev2.HasGenesis
 
 // HasABCIGenesis defines a custom genesis handling API implementation for ABCI.
 // (stateful genesis methods which returns validator updates)
 // Most modules should not implement this interface.
-type HasABCIGenesis = appmodule.HasABCIGenesis
+type HasABCIGenesis = appmodulev2.HasABCIGenesis
 
 // HasGenesisAuto is the extension interface that modules should implement to handle
 // genesis data and state initialization.
-// WARNING: This interface is experimental and may change at any time.
+// WARNING: This interface is experimental and may change at any time and has been dropped in v2.
 type HasGenesisAuto interface {
-	appmodule.AppModule
+	appmodulev2.AppModule
 
 	// DefaultGenesis writes the default genesis for this module to the target.
 	DefaultGenesis(GenesisTarget) error

core/appmodule/migrations.go

@@ -1,20 +1,20 @@
 package appmodule
 
 import (
-	"cosmossdk.io/core/appmodule/v2"
+	appmodulev2 "cosmossdk.io/core/appmodule/v2"
 )
 
 // HasConsensusVersion is the interface for declaring a module consensus version.
-type HasConsensusVersion = appmodule.HasConsensusVersion
+type HasConsensusVersion = appmodulev2.HasConsensusVersion
 
 // HasMigrations is implemented by a module which upgrades or has upgraded to a new consensus version.
-type HasMigrations = appmodule.HasMigrations
+type HasMigrations = appmodulev2.HasMigrations
 
 // MigrationRegistrar is the interface for registering in-place store migrations.
-type MigrationRegistrar = appmodule.MigrationRegistrar
+type MigrationRegistrar = appmodulev2.MigrationRegistrar
 
 // MigrationHandler is the migration function that each module registers.
-type MigrationHandler = appmodule.MigrationHandler
+type MigrationHandler = appmodulev2.MigrationHandler
 
 // VersionMap is a map of moduleName -> version
-type VersionMap = appmodule.VersionMap
+type VersionMap = appmodulev2.VersionMap

core/appmodule/module.go

@@ -3,7 +3,7 @@ package appmodule
 import (
 	"context"
 
-	"cosmossdk.io/core/appmodule/v2"
+	appmodulev2 "cosmossdk.io/core/appmodule/v2"
 	"cosmossdk.io/core/legacy"
 )
 
@@ -11,25 +11,25 @@ import (
 // for extension interfaces. It provides no functionality itself, but is the
 // type that all valid app modules should provide so that they can be identified
 // by other modules (usually via depinject) as app modules.
-type AppModule = appmodule.AppModule
+type AppModule = appmodulev2.AppModule
 
 // HasPreBlocker is the extension interface that modules should implement to run
 // custom logic before BeginBlock.
-type HasPreBlocker = appmodule.HasPreBlocker
+type HasPreBlocker = appmodulev2.HasPreBlocker
 
 // HasBeginBlocker is the extension interface that modules should implement to run
 // custom logic before transaction processing in a block.
-type HasBeginBlocker = appmodule.HasBeginBlocker
+type HasBeginBlocker = appmodulev2.HasBeginBlocker
 
 // HasEndBlocker is the extension interface that modules should implement to run
 // custom logic after transaction processing in a block.
-type HasEndBlocker = appmodule.HasEndBlocker
+type HasEndBlocker = appmodulev2.HasEndBlocker
 
 // HasRegisterInterfaces is the interface for modules to register their msg types.
-type HasRegisterInterfaces = appmodule.HasRegisterInterfaces
+type HasRegisterInterfaces = appmodulev2.HasRegisterInterfaces
 
 // ValidatorUpdate defines a validator update.
-type ValidatorUpdate = appmodule.ValidatorUpdate
+type ValidatorUpdate = appmodulev2.ValidatorUpdate
 
 // HasServices is the extension interface that modules should implement to register
 // implementations of services defined in .proto files.
@@ -55,13 +55,13 @@ type ValidatorUpdate = appmodule.ValidatorUpdate
 // HasPrepareCheckState is an extension interface that contains information about the AppModule
 // and PrepareCheckState.
 type HasPrepareCheckState interface {
-	appmodule.AppModule
+	appmodulev2.AppModule
 	PrepareCheckState(context.Context) error
 }
 
 // HasPrecommit is an extension interface that contains information about the appmodule.AppModule and Precommit.
 type HasPrecommit interface {
-	appmodule.AppModule
+	appmodulev2.AppModule
 	Precommit(context.Context) error
 }
 

core/appmodule/v2/doc.go

@@ -0,0 +1,3 @@
+// Package appmodule defines what is needed for an module to be used in the Cosmos SDK (runtime/v2).
+// If you are looking at integrating dependency injection into your module please see depinject appconfig documentation.
+package appmodulev2

core/appmodule/v2/environment.go

@@ -1,4 +1,4 @@
-package appmodule
+package appmodulev2
 
 import (
 	"cosmossdk.io/core/branch"
@@ -11,8 +11,8 @@ import (
 	"cosmossdk.io/core/transaction"
 )
 
-// Environment is used to get all services to their respective module
-// Contract: All fields of environment are always populated.
+// Environment is used to get all services to their respective module.
+// Contract: All fields of environment are always populated by runtime.
 type Environment struct {
 	Logger log.Logger
 

core/appmodule/v2/genesis.go

@@ -1,4 +1,4 @@
-package appmodule
+package appmodulev2
 
 import (
 	"context"

core/appmodule/v2/handlers.go

@@ -1,4 +1,4 @@
-package appmodule
+package appmodulev2
 
 import (
 	"context"

core/appmodule/v2/migrations.go

@@ -1,4 +1,4 @@
-package appmodule
+package appmodulev2
 
 import "context"
 

core/appmodule/v2/module.go

@@ -1,4 +1,4 @@
-package appmodule
+package appmodulev2
 
 import (
 	"context"

core/appmodule/v2/tx_validator.go

@@ -1,4 +1,4 @@
-package appmodule
+package appmodulev2
 
 import (
 	"context"