DEV Community: Jai Pradeesh

Good First Issue - Make your first open-source contribution

Jai Pradeesh — Tue, 18 Feb 2020 03:43:04 +0000

Good First Issue is an initiaitive to curate easy pickings from popular projects, so developers who've never made a contribution to open-source can get started easily.

Open-source maintainers are always looking to get more people involved, but new developers generally think it's difficult to become a contributor. We believe getting developers to fix super-easy issues removes the barrier for future contributions. This is why Good First Issue exists.

Adding a new project

You're welcome to add a new project in Good First Issue, and we encourage all projects — old and new, big and small.

Follow these simple steps:

Make sure your GitHub repository has at least one issue with the good first issue label. This label is already present on all repositories by default. If not, you can follow the steps here.
Add the repository's path in data/repositories.toml here - github.com/deepsourcelabs/good-first-issue.
Create a new pull-request. Once the pull-request is merged, the changes will be live on goodfirstissue.dev.

DeepSource Go analyzer is now generally available

Jai Pradeesh — Mon, 09 Dec 2019 07:14:35 +0000

Go programming language has taken the developer ecosystem by storm. Since it's creation in 2009, the language has seen tremendous global adoption by developers looking for a lightweight as well as expressive language suited for microservices architectures. It has been touted to be on a trajectory to become the next enterprise programming language.

DeepSource Go analyzer is now generally available and is free to use for open-source repositories.

Issue distribution

The analyzer detects 150+ types of issues falling into the following categories — bug risks, anti-patterns, security vulnerabilities, performance issues, documentation coverage and style violations.

Here's quick overview of some sample issues from each of these categories.

Bug risks

Incorrect usage of append
Using defer in infinite loops which will never execute
Invalid regular expressions
Assignment to nil map

Security vulnerabilities

Poor file permissions
Binding to all interfaces
Hard-coded credentials in source code
Use of un-escaped data in HTML templates

Performance issues

Storing non-pointer values in sync.Pool
Using time.Tick in a leaky way
Optimizations when indexing maps by byte slices

Anti-patterns

Duplicate build constraints
Trapping signals like SIGKILL and SIGSTOP that can't be trapped
Redundant control flows
Missing error checks

Style violations

Incorrectly formatted error string
Misplaced default case in switch statements

Getting Started with GitHub

Analyzing Go code with DeepSource is straightforward. Just add a .deepsource.toml file to the repository root to tell DeepSource which analyzers to run. The following example configuration will run go analysis continuously on all pull requests.

File: .deepsource.toml

version = 1

test_patterns = [
  "tests/*_test.go",
  "**/*_test.go"
]

[[analyzers]]
name = "go"
enabled = true

  [analyzers.meta]
  import_path = "github.com/username/repository"

[[analyzers]]
name = "test-coverage"
enabled = true

Tracking test coverage

You can also track test coverage for your Go code. Post enabling test coverage analyzer (above step), use DeepSource CLI to report metrics from any CI systems.

# Run your tests and generate coverage report
go test -coverprofile=coverage.out

# Install 'deepsource CLI'
curl https://deepsource.io/cli | sh

# Set DEEPSOURCE_DSN env variable from repository settings page
export DEEPSOURCE_DSN=https://sampledsn@deepsource.io

# Report coverage artifact to 'test-coverage' analyzer
./bin/deepsource report --analyzer test-coverage --key go --value-file ./coverage.out

Go build.

Package management in Go

Jai Pradeesh — Wed, 11 Sep 2019 07:50:56 +0000

Package management is one of the things Go has always missed. One of the major drawbacks of the previous (pre 1.11) go get was lack of support for managing dependency versions and enabling reproducible builds. The community has developed package managers and tools like Glide, dep and many others serving as de-facto solutions for versioning dependencies.

"I use go get for production builds." — said no one ever.

Go's implementation of package management traces its origins back to Google (which has a giant monolithic repository for all their source code). Let's break down on what's wrong with 'pre - go module' package management tooling.

Versioning dependencies
Vendoring dependencies
The necessity of GOPATH

Versioning dependencies

go get by default didn't support module versioning. The idea behind the first version of go's package management was — no need for module versioning, no need for 3rd-party module repositories, you build everything from your current branch.

Pre Go 1.11, adding a dependency meant cloning that dependency's source code repo in your GOPATH. That was about it. There was no concept of versions. Rather, it always pointed to the current master branch at the time of cloning. Another major issue cropped up when different projects needed different versions of a dependency — which wasn't possible either.

Vendoring dependencies

Package vendoring is commonly referred to as the case where dependent packages are stored in the same place as your project. That usually means your dependencies are checked into your source management system, such as Git.

Consider this case — A uses dependency B, which uses a feature of dependency C introduced in version 1.5 of C, B must be able to ensure that A's build uses C 1.5 or later. Pre Go 1.5, there was no mechanism for carrying dependency code alongside commands without rewriting import paths.

Necessity of `GOPATH`

GOPATH exists for two main reasons:

In Go, the import declaration references a package via its fully qualified import path. GOPATH exist so that from any directory inside GOPATH/src the go tool can compute the absolute import path of the package in question.
A location to store dependencies fetched by go get.

What's wrong with this?

GOPATH doesn’t allow checking out the source of a project in a directory of choice like they are used to with other languages.
Additionally, GOPATH does not let the developer have more than one copy of a project (or its dependencies) checked out at the same time.

Introducing Go Modules

Go 1.11 introduces preliminary support for Go modules. From Go Wiki,

A module is a collection of related Go packages that are versioned together as a single unit. Modules record precise dependency requirements and create reproducible builds.

Go modules brings three important features built-in,

1) go.mod file similar to package.json or Pipfile.

2) A machine-generated transitive dependency description - go.sum.

3) No more GOPATH limitation. Modules can be in any path.

$ go help mod
Go mod provides access to operations on modules.

Note that support for modules is built into all the go commands,
not just 'go mod'. For example, day-to-day adding, removing, upgrading,
and downgrading of dependencies should be done using 'go get'.
See 'go help modules' for an overview of module functionality.

Usage:

    go mod <command> [arguments]

The commands are:

    download    download modules to local cache
    edit        edit go.mod from tools or scripts
    graph       print module requirement graph
    init        initialize new module in current directory
    tidy        add missing and remove unused modules
    vendor      make vendored copy of dependencies
    verify      verify dependencies have expected content
    why         explain why packages or modules are needed

Use "go help mod <command>" for more information about a command.

Relevant discussion thread.

Migrating to Go Modules

To use Go modules, update Go to version >= 1.11. Since GOPATH is going away, one can activate module support in one of these two ways:

Invoke the go command in a directory outside of the GOPATH/src tree, with a valid go.mod file in the current directory.
Go modules don't work if source is under GOPATH. To override this behaviour, invoke the go command with GO111MODULE=on environment variable set.

Let's start porting by following these simple steps:

As GOPATH isn't necessary anymore, move the module out of GOPATH.
From the project root, create the initial module definition - go mod init github.com/username/repository. The best part is, go mod automatically converts dependencies from existing package managers like dep, Gopkg, glide and six others. This will create a file called go.mod with the module name and dependencies with its versions.

$ cat go.mod
module github.com/deepsourcelabs/cli

go 1.12

require (
    github.com/certifi/gocertifi v0.0.0-20190410005359-59a85de7f35e
    github.com/getsentry/raven-go v0.2.0
    github.com/pkg/errors v0.0.0-20190227000051-27936f6d90f9

Run go build to create a go.sum file which contains the expected cryptographic checksums of the content of specific module versions. This is to ensure that future downloads of these modules retrieve the same bits as the first download. Note that go.sum is not a lock file.

$ cat go.sum
github.com/certifi/gocertifi v0.0.0-20190410005359-59a85de7f35e h1:9574pc8MX6rF/QyO14SPHhM5KKIOo9fkb/1ifuYMTKU=
github.com/certifi/gocertifi v0.0.0-20190410005359-59a85de7f35e/go.mod h1:GJKEexRPVJrBSOjoqN5VNOIKJ5Q3RViH6eu3puDRwx4=
github.com/getsentry/raven-go v0.2.0 h1:no+xWJRb5ZI7eE8TWgIq1jLulQiIoLG0IfYxv5JYMGs=
github.com/getsentry/raven-go v0.2.0/go.mod h1:KungGk8q33+aIAZUIVWZDr2OfAEBsO49PX4NzFV5kcQ=
github.com/pkg/errors v0.0.0-20190227000051-27936f6d90f9 h1:dIsTcVF0w9viTLHXUEkDI7cXITMe+M/MRRM2MwisVow=
github.com/pkg/errors v0.0.0-20190227000051-27936f6d90f9/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=

Note on versioning: To maintain backward compatibility, if the module is version v2 or higher, the major version of the module must be included as a /vN at the end of the module paths used in go.modfiles (e.g., module github.com/username/repository/v2

Everyday commands

List dependencies

go list -m all lists the current module and all its dependencies.

$ go list -m all
github.com/deepsourcelabs/cli
github.com/certifi/gocertifi v0.0.0-20190410005359-59a85de7f35e
github.com/getsentry/raven-go v0.2.0
github.com/pkg/errors v0.0.0-20190227000051-27936f6d90f9

In the go list output, the current module, also known as the main module, is always the first line, followed by dependencies sorted by module path.

List available versions of a package

go list -m -versions github.com/username/repository lists available versions of a package.

$ go list -m -versions github.com/getsentry/raven-go
github.com/getsentry/raven-go v0.1.0 v0.1.1 v0.1.2 v0.2.0

Add a dependency

Adding a dependency is implicit. After importing a dependency in code, running go build or go test command gets the latest version of the module and adds it to go.mod file. If you would like to add a dependency explicitly, rungo get github.com/username/repository.

Upgrade/downgrade a dependency

go get github.com/username/repository@vx.x.x downloads and sets the specific version of the dependency and updates go.mod file.

$ go get github.com/getsentry/raven-go@v0.1.2
go: finding github.com/getsentry/raven-go v0.1.2
go: downloading github.com/getsentry/raven-go v0.1.2
go: extracting github.com/getsentry/raven-go v0.1.2

$ cat go.mod 
module github.com/deepsourcelabs/marvin-go

go 1.12

require (
    github.com/certifi/gocertifi v0.0.0-20190410005359-59a85de7f35e
    github.com/getsentry/raven-go v0.1.2
    github.com/pkg/errors v0.0.0-20190227000051-27936f6d90f9
)

$ cat go.sum
github.com/certifi/gocertifi v0.0.0-20190410005359-59a85de7f35e h1:9574pc8MX6rF/QyO14SPHhM5KKIOo9fkb/1ifuYMTKU=
github.com/certifi/gocertifi v0.0.0-20190410005359-59a85de7f35e/go.mod h1:GJKEexRPVJrBSOjoqN5VNOIKJ5Q3RViH6eu3puDRwx4=
github.com/getsentry/raven-go v0.1.2 h1:4V0z512S5mZXiBvmW2RbuZBSIY1sEdMNsPjpx2zwtSE=
github.com/getsentry/raven-go v0.1.2/go.mod h1:KungGk8q33+aIAZUIVWZDr2OfAEBsO49PX4NzFV5kcQ=
github.com/getsentry/raven-go v0.2.0 h1:no+xWJRb5ZI7eE8TWgIq1jLulQiIoLG0IfYxv5JYMGs=
github.com/getsentry/raven-go v0.2.0/go.mod h1:KungGk8q33+aIAZUIVWZDr2OfAEBsO49PX4NzFV5kcQ=
github.com/pkg/errors v0.0.0-20190227000051-27936f6d90f9 h1:dIsTcVF0w9viTLHXUEkDI7cXITMe+M/MRRM2MwisVow=
github.com/pkg/errors v0.0.0-20190227000051-27936f6d90f9/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=

Vendoring dependencies

When using modules, the go command completely ignores vendor directories. For backward compatibility with older versions of Go, or to ensure that all files used for a build are stored together in a single file tree, rungo mod vendor.

This creates a directory named vendor in the root directory of the main module and stores all the packages from dependency modules there.

Note: To build using the main module's top-level vendor directory, run 'go build -mod=vendor'.

Remove unused dependencies

go mod tidy trims unused dependencies and updates go.mod file.

FAQs

Is `GOPATH` not needed anymore?

No. Farewell GOPATH.

Which version is pulled by default?

The go.mod file and the go command more generally use semantic versions as the standard form for describing module versions, so that versions can be compared to determine which should be considered earlier or later than another. A module version like v1.2.3 is introduced by tagging a revision in the underlying source repository. Untagged revisions can be referred to using a "pseudo-version" like v0.0.0-yyyymmddhhmmss-abcdefabcdef, where the time is the commit time in UTC and the final suffix is the prefix of the commit hash.

Should `go.sum` be checked into version control?

Yes.

Importance of software documentation

Jai Pradeesh — Thu, 18 Jul 2019 02:32:42 +0000

Software evolves, and changes to software are inevitable. In general, any work done to change the software after it is in operation is considered to be maintenance. Maintenance consumes over 70% of the total life-cycle cost of a software project ¹. If you think about it for a while, you would realize how critical maintenance work is to keep the software alive. Interestingly, the act of reading code is the most time-consuming component of all maintenance activities performed by software developers.

Since readability poses such importance on maintenance of software, let’s understand how do we define it. In natural languages, readability is defined as how easy a text is to understand. In literature, readability is objectively judged by metrics like average syllables per word, average sentence length, etc. Raising the readability level of a text from mediocre to good can make the difference between success and failure of its communication goals.

Programs must be written for people to read and only incidentally for machines to execute. Thus spoke the authors of the authoritative book on software development patterns, SICP. So how do we make sure the communication goals of source code is delivered to the developers?

Source code is not documentation

You would often see software developers treat source code as the primary or at times, the only documentation. For this to manifest in practice, the code has to be sufficiently detailed and precise. But source code in its original form is not readable as plain text. As noted earlier, readability plays a huge part in making software accessible and maintainable. Any documentation that is written must be easy to understand not just by the immediate team members but also by future stakeholders. Some examples of why this is important are:

When interfacing with external modules, the consumer should understand the exposed interfaces by the existing module.
To extend a module, existing models and concepts need to be understood in detail.
To identify a bug and patch a fix faster, detailed documentation can be critical.

Of course, for the documentation to be effective, it must be maintained along with the code itself. When refactoring code it has to be made sure that the documentation reflects the change as well. All seasoned engineering teams put the impetus on tracking changes in documentation when the code is updated.

How to write good documentation?

Three golden rules when writing documentation are asking yourself these questions while writing comments:

What does this piece of code do?
How does it do it?
How does someone use it somewhere else?

When you treat comments as part of source code, make sure it’s reviewed along in the merge process. If there is one takeaway from this post, it is treating documentation equally as source code as part of review process.

Embedded documentation helps the programmer to stay within the context and understand thoroughly. It also exhibits a significant level of correlation with other conventional metrics such as software quality, code churn, etc. A code base is owned primarily by a team, not an individual. It’s important that developers put in the effort to make sure that the code they write is clear and readable. Some teams may prefer to skip code documentation in order to save time, money and effort. Keep in mind though that this might result in even more significant expenses once the product is transferred to another team or when updates are required down the line.

DEV Community: Jai Pradeesh

Good First Issue - Make your first open-source contribution

Adding a new project

DeepSource Go analyzer is now generally available

Issue distribution

Bug risks

Security vulnerabilities

Performance issues

Anti-patterns

Style violations

Getting Started with GitHub

Tracking test coverage

Package management in Go

Versioning dependencies

Vendoring dependencies

Necessity of GOPATH

Introducing Go Modules

Migrating to Go Modules

Everyday commands

List dependencies

List available versions of a package

Add a dependency

Upgrade/downgrade a dependency

Vendoring dependencies

Remove unused dependencies

FAQs

Is GOPATH not needed anymore?

Which version is pulled by default?

Should go.sum be checked into version control?

Importance of software documentation

Source code is not documentation

How to write good documentation?

References

Necessity of `GOPATH`

Is `GOPATH` not needed anymore?

Should `go.sum` be checked into version control?