Modules, Packages, and Imports

Modules, Packages, and Imports

1. Repositories, Modules, and Packages

   • Repositories
     • Places in version control systems where source code is stored
   • Modules
     • Bundles of Go source code distributed and versioned as a single unit
   • Packages
     • Directories of source code within modules
   • Storing multiple modules in one repository is discouraged
   • Module path
     • Globally unique identifier for a module
     • Usually based on repository location

2. Using go.mod

   • go.mod file
     • Makes a directory tree of Go source code a module
   • go mod init MODULE_PATH
     • Command to create go.mod file
   • module directive
     • Specifies module's unique path
   • go directive
     • Specifies minimum compatible Go version
   • The require Directive
     • Lists module dependencies and minimum required versions
     • Direct dependencies listed first
     • Indirect dependencies marked with // indirect comment

3. Building Packages

   • Importing and Exporting
     • import statement
       • Allows access to exported identifiers from other packages
     • Capitalization
       • Determines if an identifier is exported (uppercase) or package-private (lowercase)
   • Creating and Accessing a Package
     • Package clause
       • First line of a file
       • "package" keyword and package name
     • Import path
       • Module path + path to package within module
     • Package name should generally match directory name
   • Naming Packages
     • Use descriptive names
     • Avoid repeating package name in function/type names within the package
   • Overriding a Package's Name
     • Use alternate names when importing packages with colliding names
   • Documenting Your Code with Go Doc Comments
     • Place comments directly before the item being documented
     • Start each line with // followed by a space
     • First word should be the symbol name
     • Use blank comment lines to separate paragraphs
   • Using the internal Package
     • internal package
       • Allows sharing code among packages in a module without exposing it externally
   • Avoiding Circular Dependencies
     • Go doesn't allow circular dependencies between packages
     • Solutions
       • Merge packages
       • Move shared items to one package
       • Create a new package
   • Organizing Your Module
     • Organize code by slices of functionality to limit dependencies among packages
   • Blank imports
     • Trigger init function in a package without accessing exported identifiers

4. Working with Modules

   • Importing Third-Party Code
     • Go builds applications from source code into a single binary
     • go get
       • Command to download modules and update go.mod file
     • Include up-to-date go.mod and go.sum files in source control
   • Semantic Versioning
     • SemVer
       • SemVer: Version number format (major.minor.patch)
         • Patch
           • Bug fixes
         • Minor
           • New backward-compatible features
         • Major
           • Breaking changes

5. Versioning Your Module

   • Use tags following semantic versioning rules
   • Pre-releases
     • Append hyphen and identifier (e.g., v1.4.0-beta1)
   • Breaking changes
     • Require different import path (subdirectory or branch)
   • Overriding Dependencies
     • replace directive
       • Redirects module references to a specified fork or local path
   • retract directive
     • Indicates versions that should be ignored
   • Include comments explaining retraction reasons
   • Using Workspaces to Modify Modules Simultaneously
     • Workspaces
       • Allow working with multiple local modules
     • Commit modules to source control in dependency order when releasing

6. Publishing Your Module

   • Make module available by putting it in a version control system
   • Include LICENSE file for open source modules

Images and files in the map