DEV Community: SourceLevel

Mastering Git: The lesser-known commands you could be using (or not)

Weverton Timoteo — Wed, 16 Aug 2023 12:52:38 +0000

Navigating the vast landscape of Git commands can sometimes feel like venturing into a bustling marketplace where everyone seems to know the most popular stalls: pull, commit, push, rebase, stash, and checkout. These commands are the cornerstone of everyday version control tasks, often forming the basis of a developer's Git journey. But amidst this bustling crowd of common commands, have you ever paused to wonder, "What else can Git do?" Have you ever caught yourself in the quiet moments, pondering the existence of lesser-known Git commands that could potentially transform your workflow?

Join us as we navigate through these unexplored corners of Git, revealing commands that may have eluded your attention but can significantly enhance your mastery of version control.

`git switch`: a fresh approach to branch management

While git checkout remains a versatile command for various purposes, it also comes with the potential to inadvertently discard changes or create confusion. Enter git switch, introduced in Git version 2.23 as a dedicated tool for branch management.

Unlike the all-encompassing nature of git checkout, git switch focuses solely on simplifying branch-related operations. Its purpose is straightforward: to provide a clearer and safer way to switch branches, reducing the risk of errors and data loss.

Why Consider Using git switch?

If you've ever felt the unease of accidentally losing your work while using git checkout, git switch offers a more reassuring alternative. This command offers explicit error messages and is designed to minimize the chances of unintentional changes.

Here are some examples of how you can use git switch effectively:

Create and switch to a new branch with git switch -c my-new-branch, using the current commit as its base.
Swiftly switch to the main branch using git switch main
Return to the previous branch by employing git switch -

`git bisect`: tracking bugs down

In software development, locating a bug can be akin to finding a needle in a haystack. But fear not – the git bisect command is here to help. It's like a guided missile for tracking down the elusive bug.

Here's how it works:

Identify Known States: First, you need to identify a "good" commit (when the code worked) and a "bad" commit (when the bug surfaced).
Start Bisecting: Begin the process with:
```
git bisect start
```

Mark Known Commits: Tag the known "good" and "bad" commits:

git bisect good <good-commit>
git bisect bad <bad-commit>

Navigate Commits: Git will automatically guide you to a commit between the two states. You test your code there. To see which commit you're at:
```
git log -n 1 --oneline
```
Continue the Hunt: Based on your test, you mark the commit as "good" or "bad":
```
git bisect good  # or git bisect bad
```
Repeat Until Found: Git will automatically move to the next commit within the narrowed range. You repeat the process until you've pinpointed the bug's source.
End the Hunt: When you've found the problematic commit:
```
git bisect reset
```

This concludes the process and takes you back to the clean state and the previous HEAD before you started the bisect process.

`git notes`: Enhancing Commit Context

Git notes provide a versatile way to attach supplementary information to a commit without altering the commit itself.

Imagine you and your team found yourselves in a Git repository with less-than-ideal commit messages. Often, commits lack the necessary clarity to explain their purpose effectively. This feature allows you to enrich commits with essential context without the need to modify or rewrite commit SHA1.

How to Utilize Git Notes

Stored locally within .git/refs/notes, Git notes remain separate from the main commit data. By default, they are not pushed to the remote repository. However, this can be changed by pushing them in a manner similar to git tag:

git push origin refs/notes/commits

To retrieve existing notes from a remote repository:

git fetch origin refs/notes/commits:refs/notes/commits

Adding Notes to Commits

You can easily add notes to existing commits using the git notes add command:

git notes add -m "Introduce irreversible migrations at this point" <commit-sha1>

The m option is optional. If omitted, your default text editor will open, allowing for a more detailed explanation.
If you skip providing <commit-sha1>, the HEAD commit will be assumed.

Removing Notes

Removing notes is straightforward:

git notes remove <commit-SHA1>

Listing and Viewing Notes

To list all existing notes:

git notes list

For more in-depth insight into a specific note:

git notes show <commit-SHA1>

Unfortunately, GitHub no longer displays git notes in its UI. This adjustment, in my opinion, reflects the limited usage of these commands. By making this change, GitHub appears to be fostering a culture of encouraging developers to consistently produce improved commits without the temptation to revisit or dwell on the details of previous commits.

Sharing Diffs: `git diff` + `git apply`

Consider a common scenario: a pair programming session happens to address a specific problem. During this interaction, the most experienced developer takes the lead, demonstrating a viable solution by implementing essential changes.

As the collaborative session unfolds, these changes become crucial building blocks for the solution. To facilitate the smooth continuation of this collaborative effort, Git provides two essential commands: git diff and git apply.

Once the demonstration is complete, and the necessary changes are in place, you can encapsulate these modifications within a concise patch file:

git diff > ~/Downloads/pair_programming_session.patch

The other developer can then seamlessly incorporate these modifications into their local codebase using:

git apply pair_programming_session.patch

In this manner, Git offers an efficient mechanism for transferring insights and progress gained from collaborative coding sessions, ensuring that developmental strides are effectively communicated.

Embrace Unfamiliar Commands

I understand that consistently learning new tools and programming languages can be challenging. However, it's important to recognize that git serves as a tool for delivering your work. Thus, make it a practice to regularly peruse the official documentation and keep your git CLI updated to fully leverage its capabilities and embrace new features.

Have you ever considered integrating these commands into your workflow? I hope you've found something useful or at least identified a command to avoid using.

The Perfect Git Commit Quest

Weverton Timoteo — Mon, 07 Aug 2023 19:16:44 +0000

The Importance of Writing a Good Commit Message

When it comes to Git commits, a well-crafted message is more than just a technical necessity. It serves as documentation, providing essential context for future reference. During a git show, a descriptive commit message offers valuable insights into the changes made, aiding comprehension and troubleshooting.

Furthermore, communicating with accessible peers about implementation and modifications opens doors for constructive collaboration and alternative perspectives. Tech leads can also better understand your approach, enabling them to offer valuable advice on advancing the solution using alternate methods.

Commit Title/Header/Subject

The commit header should be concise, with a maximum length of 72 characters in GitHub, to avoid truncation with ellipsis. Ending the title with a period is unnecessary, as every character counts. Starting with an imperative mood verb, such as Add, Fix, Remove, or Refactor, sets a clear and actionable tone for the commit.

Using Conventional Commits

To provide even more context, consider following the Conventional Commits specification, which builds on the Angular Commit Guidelines. Prefix the title with specific keywords like fix, feature/feat, refactor, deploy, chore, docs, or test. Each prefix highlights the nature of the changes made.

fix: Represents a bug fix for your application.
feature / feat: Adds a new feature to your application or library.
refactor: A code change that neither fixes a bug nor adds a feature.
deploy: Changes related to the deployment process.
chore: Upgrades libraries and/or performs maintenance tasks.
docs: Documentation-only changes.
test: Adding missing tests or correcting existing tests.

Here's an example:

feature(shopping-cart): Add remove button

User can now remove the item entirely from shopping cart.

On clicking the button an animation transition will be
displayed.

https://linear.app/<workspace>/issue/A-123/add-ability-to-remove-item-from-shopping-cart

Commit Body

Adding a line break between the header and the body helps organize information clearly. You can mention the files affected by the changes and explain the purpose and accomplishments of the commit. Keeping individual lines within 100 characters enhances readability.

Add a linebreak between Header and the body
You can mention which files are included in these changes
Explain why and what was accomplished in this commit
Many tools recommends that any line cannot be longer than 100 characters, making each one more readable

Commit message conventions (Annotations)

`Co-authored-by`

Marking your pairs during commits is essential for effective collaboration, especially in pair programming (eXtreme Programming). When the author accepts the suggestions block made during a Pull Request review, GitHub doesn’t use Suggested-by convention, instead it uses Co-authored-by.

While there are more conventions to follow, in common workflows, using Co-authored-by is strongly recommended.

When to Commit?

Committing early and often throughout development is highly recommended. Delaying commits until the end of the process can create challenges in organizing atomic commits, crafting a coherent narrative, and receiving timely feedback during the Code Review process. By committing regularly, you can easily create a Draft Pull/Merge Request to seek immediate peer input.

Staging the Changes

Simplify your commit process with tools like LazyGit, tig, GitHub Desktop, Git Tower, or GitKraken. When making changes, think of each commit as a "package" that should be "revertable" through git revert without breaking the build or test suite. Run tests right after creating a commit to ensure changes do not disrupt the suite. To temporarily remove existing changes, use git stash --include-untracked, then remember to git stash pop and continue the commit process.

Forgot Something in the Previous Commit?

If you missed including a change, you can easily remedy the situation with git add followed by git commit --amend. The --amend command picks up your previous commit message (don't forget to update the details about the inclusion) before pushing it with git push.

Note that if you already pushed the commit, you'll need to use git push -f to replace the existing commit with the regenerated SHA1 commit from the amendment. If you're collaborating with others in the same branch, remind your peers to pull the changes, though no impact is expected if they haven't started working in this branch yet.

The Art of Summarize: Drafting/Opening a Pull Request

When working on a project for 2-5 days, summarizing your work in a Pull Request can be challenging. Leverage your well-crafted commit messages to read the story and provide concise summaries to your reviewers. Doing so not only streamlines the review process but also serves as documentation for future reference.

Tuning Your `git` Command

Ensure your $EDITOR is set to your favorite editor for git commit execution:

export EDITOR=nvim

You can also configure core.editor to open any git command in your preferred editor (Visual Studio Code in this example):

git config --global core.editor code --wait

Use Templates for Commit Messages

Simplify the git commit message structure by using templates:

$ git config --global commit.template ~/.gitmessage.txt
$ git commit

Not sure how to start? Use this one:

# Replace this title (<- imperative), <= 50 chars, no period

# Keep this blankline above but replace this line and below
# by your body explaining *what* and *whay* (not *how*) no
# more than 100 chars.

# Here is a footer, include the Git Conventions annotations
# you prefer, such as: 
# Co-authored-by: name <user@users.noreply.github.com>

The Journey to Better Commits: Level Up! Quest Completed!

In the journey of perfecting your Git commits, you've unlocked the art of crafting informative and context-rich messages that enhance your development process. Embracing Conventional Commits, staging your changes, and committing early and often, you've laid the foundation for collaborative and efficient code reviews.

Before marking your Pull Request as “Ready for review”, check this blog post: '10 Items to Check Before Assigning a Pull Request to Someone.' Should your team seek more opportunities for reviews, venture into the realm of 'Creating Code Review Opportunities' for valuable insights. Continue your quest for better commits and conquer new challenges, kupo!

Creating Code Reviews opportunities

Weverton Timoteo — Mon, 31 Jul 2023 18:40:52 +0000

Picture this: Your team is working on a project, and Pull/Merge Requests are piling up without any reviews. Code Reviews are not just a formality; they are an incredible opportunity to learn, grow, motivate, mentor, debate, and share knowledge. So, how can you turn this situation around and make the most out of Code Reviews to enhance your development process?

Finding Time Slots - Optimizing Your Review Routine

Reviewing code shouldn't be an added burden to your team's daily tasks. Instead, seamlessly integrate it into your workflow by using available time slots. Take advantage of moments like coffee breaks, filling your water bottle, grabbing a coffee, or just before lunchtime and wrapping up the day. By incorporating these review moments into your daily rhythm, you ensure consistent Code Reviews without disrupting your workflow, promoting a culture of continuous improvement.

Using Interruptions to Your Advantage

Interruptions are unavoidable, but they can also be opportunities for the Code Review process. When interrupted, use the time to review code. Seamlessly integrate Code Reviews into various workflow transitions, such as finishing user stories, pulling new user stories, opening pull requests, merging pull requests, and ending pair programming sessions.

Dedicate specific time slots for reviews to ensure a focused approach. Avoid rushing reviews under time pressure; communicate time constraints and plan for thorough reviews. Prioritize quality over quantity; thoroughly review a few Pull Requests rather than performing hasty, superficial reviews.

Maximizing Collaboration: Pair Programming's Hidden Gem - Code Reviews

Pair programming fosters collaboration and knowledge sharing. At the end of a session, leverage this opportunity for collaborative Code Reviews. Engage in open discussions, share feedback, document decisions, and celebrate successes, boosting collaboration, code quality, and a culture of continuous learning and growth.

Empowering Psychological Safety in Code Review Discussions

Prioritize psychological safety to enhance team collaboration and code quality. Encourage openness and embrace diverse perspectives during reviews. Deliver feedback respectfully and focus on the code, not the developer. Lead by example, treat mistakes as learning opportunities, and provide guidance to support less experienced team members. Welcome questions and set clear expectations for Code Reviews.

Empowering psychological safety encourages questions and fosters a welcoming environment for other reviewers to participate and interact. Your team can foster a culture of trust, continuous improvement, and code excellence.

Optimizing Code Reviews with Available Tools

Streamline the Code Review process and avoid overlooking reviews by using available tools. GitHub Reminders, integrated with Slack, improve communication and collaboration. Assigned "Reviewers" receive direct messages, ensuring timely notifications. Configure a Slack channel to receive daily reminders, helping the team stay informed and address reviews promptly.

Fostering Accountability through Code Reviews

Code Reviews promote accountability within your team. As "Reviewers," team members take ownership of the codebase, ensuring it meets the team's standards. A culture of mutual support and continuous improvement emerges, enhancing overall productivity and code quality.

Embrace a Strong Code Review Culture

Before assigning a Pull Request to someone, consider taking a moment to review it yourself. By ensuring your PR is well-prepared and clear, you set the stage for efficient and effective feedback sessions. To optimize your Code Review process and discover essential tips for preparing Pull Requests, explore our blog post here.

With a proactive approach to Code Reviews and a commitment to continuous learning, your team will thrive in a collaborative and supportive environment.

Sunsetting SourceLevel’s Automated Code Review feature: What’s next?

Weverton Timoteo — Wed, 15 Jun 2022 20:13:05 +0000

When we launched SourceLevel, we had a great focus on Automated Code Review, through 30+ Open Source linters (including support for Ruby, JavaScript, Elixir, Golang, PHP, Python, etc.). During product validation we have introduced some use case metrics which includes Work In Progress, Engagement, and Deliveries.

Last year, we released a new product completely focused on Engineering Metrics. And we’ve decided to sunset the Automated Code Review feature, improving our Analytics product bringing visibility over every corner of the delivery pipeline in a Data & Analytics Solution for Engineering Teams.

We still consider Code Quality metrics relevant, but we don’t think we should keep running the linters since a lot of free alternatives are available to be included in your Continuous Integration pipeline, such as GitHub Actions.

In the future, we are considering importing issues identified by these runners through our API. We’d recommend including the linter that you use to your GitHub Actions pipeline or consider installing Danger.systems (which supports Ruby, Python, Swift, Kotlin, and JavaScript) for your organization.

We’ll start contacting existing customers to notify about Automated Code Review sunset and schedule a turn-off customer-by-customer.

Currently, Analytics is providing metrics for Software Engineering Management, to see a glimpse of what we offer, go to our Engineering Metrics page.

RuboCop: How to install and configure

Gustavo Araujo — Tue, 15 Mar 2022 14:07:51 +0000

That Code quality is important, and any high-performing team knows it, but do you follow a guideline to standardize your codebase and make sure that everyone is going and looking in the same direction?

Making a brief introduction, this is the goal of a linter: A tool that analyzes your source code to identify programming errors, bugs, and suspicious constructions (Wikipedia).

The main objective is to ensure that your code follows the same rules and practices, to look like the entire code was written by the same person.

In a large variety of linters from Ruby, we have RuboCop (available as a gem) that follows the best practices described in The Ruby Style Guide.

One of the advantages of using a linter is to save time reviewing code because it prevents small issues like inconsistent variable names and practices during the development process. With that, the code review is more efficient, and it can be focused on implementations and features requirements.

Starting using RuboCop is very straightforward and doesn’t depend on anyone else to setup it. You can install the gem and run it immediately during your workflow.

Installation

To install the RuboCop, it’s quick and easy. Let's consider here that all your Ruby environment is working, so just execute the following command to install the latest RuboCop version available:

$ gem install rubocop

RuboCop officially supports the MRI 2.5+ and jRuby 9.2+ implementations. You can also install directly in the project using Bundler, adding the gem to your Gemfile, and then run bundle install.

Configuration

The RuboCop behavior can be controlled in the .rubocop.yml file in the root path where you want to execute it. In this file, you can enable/disable certain cops (rules) or change their behavior.

All cops are grouped into departments: Style, Layout, Lint, Naming, Security, Metrics, Migration, Bundler, and Gemspec. You can read about the cops and their departments in the documentation. For reference purposes, check the configuration file that we use in SourceLevel in our linter’s configuration repository.

The .rubocop.yml file has the following structure:

inherit_from: ../.rubocop.yml

require: rubocop-rails

Style/Encoding:
  Enabled: false

Layout/LineLength:
  Max: 99

...

Note 1: We’re using inherit_from to inherit all defined cops in the other file. See more in the documentation.
Note 2: If you’re using **Rails, it’s important to require the rubocop-rails extension (remember to add it to your Gemfile), which will force RuboCop to follow the conventions and good practices defined by the Rails community.

By default, when executed, the RuboCop looks for .rubocop.yml in the current directory, then in your home path (~/.rubocop.yml), and in the last case it will use the defaults. More details about RuboCop’s configuration file can be found on the documentation.

If you want to create your configuration file, which I encourage, a good starting point is to use the configuration available in the RuboCop repository as a reference. You can review cop by cop and configure what suits you. Just remember to check the cop availability for the version of RuboCop that you’re using.

Keep in mind that style rules that belong to the Style namespace are configurable and optional. A good recommendation is that these rules need to be discussed and defined with the entire team, not by a single person.

It’s nice to mention that you can write your own cops, called Custom Cops. With that, you can create your own rules, defining your practices to ensure that they will be followed. You can find more information about this process in documentation.

Usage

To use the RuboCop you just need to navigate to the directory where you want to run the linter, and execute:

$ rubocop

You can specify a file/path too:

$ rubocop lib/file.rb

It’s possible to specify a list of directories and files:

$ rubocop app/ spec/ lib/file.rb

After running RuboCop, you’ll get an output with offenses, like:

Offenses:

test.rb:1:1: C: Style/FrozenStringLiteralComment: Missing magic comment # frozen_string_literal: true.
def badName
^
test.rb:1:5: C: Naming/MethodName: Use snake_case for method names.
def badName
    ^^^^^^^
test.rb:2:3: C: Style/GuardClause: Use a guard clause instead of wrapping the code inside a conditional expression.
  if something
  ^^
test.rb:2:3: C: Style/IfUnlessModifier: Favor modifier if usage when having a single-line body. Another good alternative is the usage of control flow &&/||.
  if something
  ^^
test.rb:4:5: W: Layout/EndAlignment: end at 4, 4 is not aligned with if at 2, 2.
    end
    ^^^

1 file inspected, 5 offenses detected

Autocorrecting

A great thing about RuboCop is the autocorrecting feature. This option fix automatically all possible offenses in your code, based on defined rules. In our case, we use -a that fix safe offenses, but you can be more optimistic and use -A to fix all offenses (including unsafe), but you need to use it with caution.

To use them, you just need to run RuboCop with this autocorrecting argument:

$ rubocop --auto-correct
# or
$ rubocop -a

You can check all RoboCop’s arguments using the --help:

$ rubocop --help

Just for linking purposes, you can check the documentation to know more about autocorrect.

Integrating with other tools

RuboCop integrates with many other tools. You may integrate it into your code editor to run it every time you save a file, and you'll immediately get its insights.

For a list of currently supported code editors, you can check this page on documentation, and if your favorite is not listed, it’s a great opportunity to contribute to RuboCop implementing an integration.

Another great usage is creating a Git Hook to run RuboCop before every commit. You can also setup RuboCop to be run into your Continuous Integration service (such as GitHub Actions) to have some insights for every commit. In all cases, more details can be found in the documentation.

I hope you enjoyed the content, and thank you for reading.

State of Golang linters and the differences between them

Weverton Timoteo — Tue, 18 Jan 2022 10:45:27 +0000

Golang is full of tools to help us on developing securer, reliable, and useful apps. And there is a category that I would like to talk about: Static Analysis through Linters.

What is a linter?

Linter is a tool that analyzes source code without the need to compile/run your app or install any dependencies. It will perform many checks in the static code (the code that you write) of your app.

It is useful to help software developers ensure coding styles, identify tech debt, small issues, bugs, and suspicious constructs. Helping you and your team in the entire development flow.

Linters are available for many languages, but let us take a look at the Golang ecosystem.

First things first: how do linters analyze code?

Most linters analyzes the result of two phases:

Lexer

Also known as tokenizing/scanning is the phase in which we convert the source code statements into tokens. So each keyword, constant, variable in our code will produce a token.

Parser

It will take the tokens produced in the previous phase and try to determine whether these statements are semantically correct.

Golang packages

In Golang we have scanner, token, parser, and ast (Abstract Syntax Tree) packages. Let's jump straight to a practical example by checking this simple snippet:

package main

func main() {
    println("Hello, SourceLevel!")
}

Okay, nothing new here. Now we'll use Golang standard library packages to visualize the ast generated by the code above:

import (
    "go/ast"
    "go/parser"
    "go/token"
)

func main() {
    // src is the input for which we want to print the AST.
    src := `our-hello-world-code`

    // Create the AST by parsing src.
    fset := token.NewFileSet() // positions are relative to fset
    f, err := parser.ParseFile(fset, "", src, 0)
    if err != nil {
        panic(err)
    }

    // Print the AST.
    ast.Print(fset, f)
}

Now let's run this code and look the generated AST:

 0  *ast.File {
 1  .  Package: 2:1
 2  .  Name: *ast.Ident {
 3  .  .  NamePos: 2:9
 4  .  .  Name: "main"
 5  .  }
 6  .  Decls: []ast.Decl (len = 1) {
 7  .  .  0: *ast.FuncDecl {
 8  .  .  .  Name: *ast.Ident {
 9  .  .  .  .  // Name content
16  .  .  .  }
17  .  .  .  Type: *ast.FuncType {
18  .  .  .  .  // Type content
23  .  .  .  }
24  .  .  .  Body: *ast.BlockStmt {
25  .  .  .  .  // Body content
47  .  .  .  }
48  .  .  }
49  .  }
50  .  Scope: *ast.Scope {
51  .  .  Objects: map[string]*ast.Object (len = 1) {
52  .  .  .  "main": *(obj @ 11)
53  .  .  }
54  .  }
55  .  Unresolved: []*ast.Ident (len = 1) {
56  .  .  0: *(obj @ 29)
57  .  }
58  }

As you can see, the AST describes the previous block in a struct called ast.Filewhich is compound by the following structure:

type File struct {
    Doc        *CommentGroup   // associated documentation; or nil
    Package    token.Pos       // position of "package" keyword
    Name       *Ident          // package name
    Decls      []Decl          // top-level declarations; or nil
    Scope      *Scope          // package scope (this file only)
    Imports    []*ImportSpec   // imports in this file
    Unresolved []*Ident        // unresolved identifiers in this file
    Comments   []*CommentGroup // list of all comments in the source file
}

To understand more about lexical scanning and how this struct is filled, I would recommend Rob Pike talk.

Using AST is possible to check the formatting, code complexity, bug risk, unused variables, and a lot more.

Code Formatting

To format code in Golang, we can use the gofmt package, which is already present in the installation, so you can run it to automatically indent and format your code. Note that it uses tabs for indentation and blanks for alignment.

Here is a simple snippet from Go by Examples unformatted:

package main

import "fmt"
func intSeq() func() int {
    i := 0

    return func() int {
        i++
        return i
    }
}

func main() {

    nextInt := intSeq()

        fmt.Println(nextInt())
    fmt.Println(nextInt())
       fmt.Println(nextInt())

    newInts := intSeq()
    fmt.Println(newInts())

}

Then it will be formatted this way:

package main

import "fmt"

func intSeq() func() int {
    i := 0

    return func() int {
        i++
        return i
    }
}

func main() {

    nextInt := intSeq()

    fmt.Println(nextInt())
    fmt.Println(nextInt())
    fmt.Println(nextInt())

    newInts := intSeq()
    fmt.Println(newInts())

}

So we can observe that import earned an extra linebreak but the empty line after main function declaration is still there. So we can assume that we shouldn’t transfer the responsibility of keeping your code readable to the gofmt: consider it as a helper on accomplishing readable and maintainable code.

It’s highly recommended to run gofmt before you commit your changes, you can even configure a precommit hook for that. If you want to overwrite the changes instead of printing them, you should use gofmt -w.

Simplify option

gofmt has a -s as Simplify command, when running with this option it considers the following:

An array, slice, or map composite literal of the form:

    []T{T{}, T{}}

will be simplified to:

    []T{{}, {}}

A slice expression of the form:

s[a:len(s)]

will be simplified to:

s[a:]

A range of the form:

for x, _ = range v {...}

will be simplified to:

for x = range v {...}

Note that for this example, if you think that variable is important for other collaborators, maybe instead of just dropping it with _ I would recommend using _meaningfulName instead.

A range of the form:

for _ = range v {...}

will be simplified to:

for range v {...}

Note that it could be incompatible with earlier versions of Go.

Check unused imports

On some occasions, we can find ourselves trying different packages during implementation and just give up on using them. By using [goimports package](https://pkg.go.dev/golang.org/x/tools/cmd/goimports) we can identify which packages are being imported and unreferenced in our code and also add missing ones:

go install golang.org/x/tools/cmd/goimports@latest

Then use it by running with -l option to specify a path, in our case we’re doing a recursive search in the project:

go imports -l ./..
../my-project/vendor/github.com/robfig/cron/doc.go

So it identified that cron/doc is unreferenced in our code and it’s safe to remove it from our code.

Code Complexity

Linters can be also used to identify how complex your implementation is, using some methodologies as example, let’s start by exploring ABC Metrics.

ABC Metrics

It’s common nowadays to refer to how large a codebase is by referring to the LoC (Lines of Code) it contains. To have an alternate metric to LoC, Jerry Fitzpatrick proposed a concept called ABC Metric, which are compounded by the following:

(A) Assignment counts: = , *= , /=, %=, +=, <<=, >>=, &=, ^=, ++, and --
(B) Branch counts when: Function is called
(C) Conditionals counts: Booleans or logic test (?, <, >, <=, >=, !=, else, and case)

Caution: This metric should not be used as a “score” to decrease, consider it as just an indicator of your codebase or current file being analyzed.

To have this indicator in Golang, you can use [abcgo package](https://github.com/droptheplot/abcgo):

$ go get -u github.com/droptheplot/abcgo
$ (cd $GOPATH/src/github.com/droptheplot/abcgo && go install)

Give the following Golang snippet:

package main

import (
    "fmt"
    "os"

    "my_app/persistence"
    service "my_app/services"

    flag "github.com/ogier/pflag"
)

// flags
var (
    filepath string
)

func main() {
    flag.Parse()

    if flag.NFlag() == 0 {
        printUsage()
    }

    persistence.Prepare()
    service.Compare(filepath)
}

func init() {
    flag.StringVarP(&filepath, "filepath", "f", "", "Load CSV to lookup for data")
}

func printUsage() {
    fmt.Printf("Usage: %s [options]\n", os.Args[0])
    fmt.Println("Options:")
    flag.PrintDefaults()
    os.Exit(1)
}

Then let’s analyze this example using abcgo:

$ abcgo -path main.go
Source            Func         Score   A   B   C
/tmp/main.go:18   main         5       0   5   1
/tmp/main.go:29   init         1       0   1   0
/tmp/main.go:33   printUsage   4       0   4   0

As you can see, it will print the Score based on each function found in the file. This metric can help new collaborators identify files that a pair programming session would be required during the onboarding period.

Cyclomatic Complexity

Cyclomatic Complexity in another hand, besides the complex name, has a simple explanation: it calculates how many paths your code has. It is useful to indicate that you may break your implementation in separate abstractions or give some code smells and insights.

To analyze our Golang code let use [gocyclo package](https://github.com/fzipp/gocyclo):

$ go install github.com/fzipp/gocyclo/cmd/gocyclo@latest

Then let’s check the same piece of code that we’ve analyzed in the ABC Metrics section:

$ gocyclo main.go
2 main main main.go:18:1
1 main printUsage main.go:33:1
1 main init main.go:29:1

It also breaks the output based on function name, so we can see that the main function has 2 paths since we’re using if conditional there.

Style and Patterns Checking

To verify code style and patterns in your codebase, Golang already came with [golint](https://github.com/golang/lint) installed. Which was a linter that offer no customization but it was performing recommended checks from the Golang development team. It was archived in mid-2021 and it is being recommended Staticcheck be used as a replacement.

Golint vs Staticcheck vs revive

Before Staticcheck was recommended, we had revive, which for me sounds more like a community alternative linter.

As revive states how different it is from archived golint:

Allows us to enable or disable rules using a configuration file.
Allows us to configure the linting rules with a TOML file.
2x faster running the same rules as golint.
Provides functionality for disabling a specific rule or the entire linter for a file or a range of lines.
golint allows this only for generated files.
Optional type checking. Most rules in golint do not require type checking. If you disable them in the config file, revive will run over 6x faster than golint.
Provides multiple formatters which let us customize the output.
Allows us to customize the return code for the entire linter or based on the failure of only some rules.
Everyone can extend it easily with custom rules or formatters.
Revive provides more rules compared to golint.

Testing revive linter

I think the extra point goes for revive at the point of creating custom rules or formatters. Wanna try it?

$ go install github.com/mgechev/revive@latest

Then you can run it with the following command:

$ revive -exclude vendor/... -formatter friendly ./...

I often exclude my vendor directory since my dependencies are there. If you want to customize the checks to be used, you can supply a configuration file:

# Ignores files with "GENERATED" header, similar to golint
ignoreGeneratedHeader = true

# Sets the default severity to "warning"
severity = "warning"

# Sets the default failure confidence. The semantics behind this property
# is that revive ignores all failures with a confidence level below 0.8.
confidence = 0.8

# Sets the error code for failures with severity "error"
errorCode = 0

# Sets the error code for failures with severity "warning"
warningCode = 0

# Configuration of the `cyclomatic` rule. Here we specify that
# the rule should fail if it detects code with higher complexity than 10.
[rule.cyclomatic]
  arguments = [10]

# Sets the severity of the `package-comments` rule to "error".
[rule.package-comments]
  severity = "error"

Then you should pass it on running revive:

$ revive -exclude vendor/... -config revive.toml -formatter friendly ./...

What else?

As I’ve shown, you can use linters for many possibilities, you can also focus on:

Performance
Unused code
Reports
Outdated packages
Code without tests (no coverage)
Magic number detector

Feel free to try new linters that I didn’t mention here, I’d recommend the archived repository awesome-go-linters.

Where to start?

To start, consider using gofmt before each commit or whenever you remember to run, then try revive. Which linters are you using?

3 better Engineering Metrics uses for Managers

George Guimarães — Fri, 12 Mar 2021 18:30:55 +0000

Many managers use engineering metrics to set goals. They measure the product delivery process and then use these numbers to set OKRs, attach to a pay raise or promotion, or micromanage. All the ways lead to pressure for achieving a specific number.

I’ve worked in teams in which managers would make leaderboards and control every individual’s output. It didn’t solve the problem, though. Micromanaging only increases illusory productivity, not the performance itself.

At the cultural level, it changes how the team dynamic works. Individualism increases and the team starts to make bad engineering decisions. The focus becomes to be at the top of the leaderboard, not delivering an excellent product.

There are other ways to use metrics. They serve multiple purposes, and managers can use them on different occasions. In this article, I listed three better ways to use metrics within engineering teams.

Metrics to motivate the team

Nobody likes to have their work wasted because of misalignments. Engineers want to work on what’s important and relevant. Add challenges to the equation, and engineers will have fun doing their jobs.

In this sense, managers need to communicate what’s most important clearly. If the team understands the plan, it is easier for them to see how they fit.

Some kinds of work are fast, and the team stays motivated from the beginning to the end. However, when an activity takes too much time, the team may lack the feeling of achievement. When it happens, morale and motivation tend to drop. Managers can avoid it by establishing smaller, tangible, and measurable milestones in the long run.

If a team has 30 technical debts that need to be addressed, managers can break it into a doable plan. It can be fixing one technical debt by a week or fixing ten up to the end of the quarter. The tactics don’t matter.

The crucial thing here is to enable the team to sense progress. Every week the leader can discuss the progress. In this case, metrics are not micromanaging anyone. They’re an indicator of progress. If the improvement is not satisfactory, that’s the right moment to change the plans, not blame.

Regularly looking to a metric towards a plan brings a sense of progress and a frequent feeling of achievement. That’s great. Besides, don’t hesitate to celebrate small and big wins. Both are essential.

Metrics as indicators

Metrics don’t tell the story; the context does. Metrics are merely a quantitative view of the facts. That’s important to have in mind when measuring, especially for those metrics that managers take as productivity.

The usage of indexes differs from traditional goals. Goals are future-centric and represent where the team should be from now. Indexes, on the other hand, show the present, like an indicator.

Therefore, a better approach is using Engineering Metrics as indicators. The hardest part is to find the appropriate set of metrics to compose the index.

For example, the Lead Time for Change, which measures from commit to deployment, is an excellent index of how fast the team works. It includes many outputs — commits, pull requests, deployments — and practices — coding, testing, DevOps, Product.

When it comes to quality, the problem can be more complicated. As quality is subjective, engineering managers may diverge.

Choosing the correct set of metrics depends on many aspects, such as team maturity, the company’s strategic goals, and product positioning. It could be the number of bugs found in production or the meantime to a system to recover from failure.

There are many metrics that we could use. Collaboration, culture, quality are all abstract terms that need a measurement. Once it’s covered, tracking indexes’ evolution over time can point to real-life changes.

I recommend starting with what seems obvious, then polish it as you learn.

Experimentation and innovation

In the last years, lots of frameworks, practices, and tools came out. Some of them changed the way we develop software — Spotify Model, to cite a famous one. They usually come from big companies that have a culture of experimenting.

Not every experiment needs to be that big and successful, though. Small improvements in the system are enough for our daily activities. But how can we tell whether an experiment has worked or not? Yes, metrics.

If managers measure outcomes instead of outputs, metrics become a powerful tool for empowering engineering teams with autonomy and responsibility.

The teams themselves can look at the metrics as indicators and tell whether their initiatives are working or not. They can try new practices, change the process, and dive into innovation. The only restriction would be not changing metrics for the bad.

Growth Marketers use this dynamic in daily operations. And I believe engineering teams should benefit from it as well.

The secret of enabling innovation is an instrumented system and strategic experimentation. There must be a rationale behind each initiative. And metrics will tell how successful they are.

To make it useful, it requires a fast feedback loop. It would be costly if every experiment had to run for months to determine its success. Early feedback — looking at how metrics behave — enables changing directions when things are not going well.

In short

Metrics shouldn’t be villains. They are a vital tool for modern software development. There is no space for micromanaging anymore because it just doesn’t work.

I listed in this article three better uses for metrics than comparing individuals against their peers.

In summary, we should look for metrics as indicators. They can motivate the team, tell how the system responds to daily activities, and enable innovation through experimentation.

SourceLevel provides a set of metrics that managers can use as indicators. If you’re unsure about what to measure, apply for a Free Strategy Session with me. If you’re wondering how to implement pragmatic metrics in your team, Schedule a Demo, and I will be happy to show.

The post 3 better Engineering Metrics uses for Managers appeared first on SourceLevel.

Three signs your team needs Engineering Metrics ASAP

George Guimarães — Thu, 28 Jan 2021 17:36:25 +0000

I’ve been using Engineering Metrics for a while, and I am amazed by the significant impacts on engineering teams. Metrics is a topic I genuinely care about. During my days at Plataformatec, we used to discuss a lot about them. At the time, we used to focus on an Agile perspective.

Our team was not satisfied in measuring Velocity in Story Points, nor we thought that estimating was helpful. So, we dug into Kanban philosophy and learned new statics techniques.

We found out that measuring the cards’ flow through the board was more accurate and useful and that forecasting using Monte Carlo could give us more realistic estimations.

Despite having many customers, we discovered that most of them had similar problems: lack of visibility and alignment. Once we introduced our metrics, the product teams had a north star.

Besides, we also noticed that many CTOs had no metric to show to the board. The CMO could prove they were bringing qualified leads, the CFO had data to show their team reduced costs, but CTOs usually had no concrete metrics.

Well, in summary, that’s the story behind SourceLevel. Over time, we received lots of valuable feedback, and we’re confident our product is in the right direction. We are helping companies to accelerate their deliveries sustainably and effectively.

For this article, I separated three signs that you need Engineering Metrics in your teams. Check if you identify with any.

#1 — You don’t know in which step of the product delivery bottleneck is.

For a commit to reach production, the code goes through a lot of steps. Many of them rely on human activities, like coding and peer-reviewing. The nature of this kind of work varies in quantity, time spent, and many other intrinsic variables.

When you analyze the big picture, engineers in all levels of experience collaborate to solve a diverse type of demand, from bugs to refactorings, from typos to new releases, and so on.

Systems are more complex than the sum of the parts. That’s why measuring individuals make no sense. The outputs produced vary too much in sizes, shapes, and purposes.

Besides, overseeing everything is very difficult. It increases significantly when the team scales up. So, you need to instrument each step by gathering data from commits, pull requests, and deploys — as a start —, so that you can inspect them to find improvement opportunities.

If you think there’s no bottleneck in your process or don’t know where it is, I strongly recommend instrumenting your system with Engineering Metrics.

#2 — You don’t have any metric to report upwards.

Every area has its standard metrics. You work for many companies, but the CMO or CFO, for instance, will always report pretty much the same metrics. However, the engineering area still doesn’t have a consolidated metric to report upwards.

I’ve seen many CTO fail because they couldn’t prove the team was making progress or that demand was over the capacity. Many executives still rely on gut feelings and outdated estimating methods.

By measuring the whole process and then being able to drill down on specific parts of the system, CTOs and managers can understand their initiatives’ impact and create better reports.

#3 — You don’t know whether the team is making progress towards desired outcomes.

When you focus on outputs, the results usually don’t go along with the outcomes. If the team’s productivity is measured by how many Pull Requests get merged, smart engineers will close as many Pull Requests as possible. It doesn’t matter whether the team reviewed it properly.

The organizational culture is abstract and changes frequently. Metrics are a crucial factor. Measuring the outputs, as the number of Merged Pull Requests, isn’t enough. Leaders need to measure the outcomes.

The engineering outcome is not only “code in production.” As a delivery system, we want engineering to deliver clean, well-tested, and reliable code to production faster in a sustainable — and predictable — way.

When the leaders spread this message across all teams and give the team autonomy to do whatever change they need, we have the benefits of measuring outcomes: teams are not attached to outputs to experiment and innovate. The chosen set of metrics provides the alignment.

For example, a way to deliver faster would be moving from a Pull Request approach to a trunk-based one. It can accelerate deliveries, but on the other hand, would the code still be well-tested and reliable? If the team is not mature enough, there are great chances it would not.

That said, after defining the outcomes for your engineering success, I strongly recommend looking for a set of metrics that reflects the results.

Do you want to know more about Engineering Metrics?

If you want to read more about Engineering Metrics, I’ve written a lot about them recently. You can find them under this category.

Feel free to schedule a 15-min chat with me to talk about the challenges at your company. Maybe, I can handle more resources for you.

The post Three signs your team needs Engineering Metrics ASAP appeared first on SourceLevel.

3 Benefits of DevOps Metrics within Engineering Teams

George Guimarães — Thu, 14 Jan 2021 18:33:44 +0000

DevOps metrics is a trending topic among software engineering managers. These metrics became very popular after the publication of Accelerate — The Science of Lean Software and DevOps: Building and Scaling High Performing Technology Organizations and the yearly The State of DevOps reports.

If you’re not familiar, here’s are the 4 DevOps Metrics proposed by the work:

Delivery Lead Time, which is also known by Lead Time for Change or Cycle Time
Deployment Frequency, also known as Delivery Throughput
Time to Restore Service
Change Fail Rate

If you search for “DevOps metrics,” you’ll quickly find many articles listing much more than four of them. Although I wouldn’t say they’re wrong, that’s something we need to pay attention to. Overseeing too many metrics — or DevOps KPIs, to cite a common term — at once can bring more problems than solutions.

For this article, I prepared a brief list with three benefits of using those metrics so that you can accelerate engineering deliveries at your place.

Benefit #1 — They consider only the engineering scope.

In the article A primer on engineering delivery metrics — Scaling software & systems, Buritica states that the product conception and design phase varies too much and then defends measuring what the engineering team is responsible for: from commit to deploy.

It makes sense. The product design phase defines what should be built, and considering it as engineering work distorts its efficiency. On the other hand, focusing on the product delivery phase allows managers to understand precisely how shipping code to production works.

In short, DevOps metrics show the big picture of your whole engineering process.

Benefit #2 — It promotes collaboration and alignment.

I don’t believe in developer or engineer productivity. Metrics such as the number of Lines of Code added, commits, and user story points delivered usually bring anxiety, depression, and burnout — to cite a few of them mentioned in Isaac Lyman’s article Can developer productivity be measured?

Modern Software Development requires collaboration. More than that, it relies on teamwork. It’s like a complex system that needs a hint of chaos to work appropriately. Because of that, it’s useless to measure individual productivity. If you measure each individual by inputs or outputs, the system will adapt to it, and then you’ll see a local improvement.

However, what about the other vital aspects of engineering success, such as quality, stability, and maintainability? The team probably won’t take them into account during the daily activities because what matters at the end of the day is to reach a certain number of inputs or outputs done.

In my opinion, this is a management anti-pattern. If we want engineering teams to collaborate, then we need to see how they work together. Every institutionalized practice, process, or automation changes how the system behaves altogether.

That’s why you need metrics that fully represent the big picture to understand if they have improved or worsened the team’s dynamic. As a result, teams work with high autonomy guided by the alignment provided by metrics that tell what’s expected from them.

Benefit #3 — Improving the system is more effective.

If you compare two individuals, given they’re humans, it very likely they won’t perform the same. Depending on the type of demand — whether it’s a bug, a new feature, or PoC —, their motivation, how clear the task, the related experiences they had, and many other aspects can cause divergences in the numbers.

In a Leaderboard, there will always have someone at the bottom. Even if you start a mentorship program to leverage individual productivity, it doesn’t mean all engineers will produce the same.

However, you can find whether a mentorship program is working by looking at the system. If the system is delivering more, with quality and reliability, it’s working. It doesn’t matter who is at the bottom or the top of the Leaderboard.

Daniel Markovitz wrote in an article for the Harvard Business Review called Productivity Is About Your Systems, Not Your People:

As legendary statistician and management consultant W. Edwards Deming argued in his book Out of the Crisis, 94% of most problems and possibilities for improvement belong to the system, not the individual. I would argue that most productivity improvements belong there as well. Personal solutions can be useful, but the most effective antidote to low productivity and inefficiency must be implemented at the system level, not the individual level.

Understanding the impact of engineering initiatives, projects, and daily activities on the system outcomes makes it much more likely to managers drive their teams to high-performance.

You’ll probably need more metrics later.

DevOps metrics are enough for having the big picture. But sometimes, we need to zoom in and see how the system behaves in a specific part of the process. In this case, you’ll need more metrics.

You may have a better idea of what I’m talking about reading Smruti Patel’s article Debugging engineering velocity and leading high-performing teams — Productivity & Eng velocity. Breaking the process into smaller steps is fundamental to understand where bottlenecks and issues are. Then, managers can complement their view by instrumenting those steps.

These complementary metrics give managers visibility and allow the teams to detach from inputs and outputs. So, they can elaborate on sophisticated solutions that impact the whole system.

However, the team should align every action with those 4 DevOps Metrics.

In short

The 4 DevOps Metrics are excellent to give managers a big view. However, to debug the process, they need to instrument the system using other metrics. It’s like Observability, but for the process.

For more ideas of how and what to measure, I strongly recommend our latest e-book, The Engineering Manager’s Play for debuggable and observable processes. It has quality content with examples of what to measure in each delivery phase.

See Engineering Metrics Live: Click here to get a full demo of SourceLevel Engineering Metrics and how they can help your team.

The post 3 Benefits of DevOps Metrics within Engineering Teams appeared first on SourceLevel.

Why you should adopt a community-maintained javascript style guide

George Guimarães — Tue, 01 Dec 2020 11:35:00 +0000

Airbnb’s JavaScript style guide is the most popular set of rules for code standardization available. The repository is open for contributions on GitHub. Yet, other style guides follow the same approach. They’re well maintained and available for free, such as Google‘s, Standard‘s, and Idiomatic‘s.

If you search more deeply, you can find even more style guides used by tech companies or individuals. There’s not a single way to write and format code, and that’s good and healthy.

However, even with lots of conventions documented out there, many companies prefer to write their version, which usually leads to a waste of time and effectiveness, as gathering the team to discuss aesthetic aspects of the code can be both time-consuming and exhausting.

In this article, I list reasons to enforce my opinion that choosing a community-maintained javascript style guide is the best thing for everyone — with few exceptions.

Maintaining a style guide is time-consuming

Each engineer develops a preference over time. Some people prefer tabs, others space; some prefer single quotes, others double quotes; and so on. Does the preference affect the quality of the code? I don’t think so. Does the preference affect the end-users value perception? I don’t believe it.

The fact is that quality and value aren’t expressed on coding preferences. They derive from solid processes and tools that support engineering activities. So, instead of focusing on discussing preferences, it’s more productive to focus on designing robust and well-crafted systems.

It’s fundamental to say that engineering teams and product final users benefit from a standardized codebase. The more a codebase looks like written by a single person, the faster and less buggy the development tends to be.

In this case, writing a document that states how code should look is not enough. It’s necessary to adopt and institutionalize as a practice, and the best tools available for that are linters. Linters use static code analysis to find mismatches. Examples include eslint and prettier for JavaScript, pylint for python, and rubocop for Ruby.

Community-maintained projects run this discussion with a broad reach, and detach those discussions to engineering daily activities. Maintenance is more frequent and peer-reviewed than in-house solutions.

Maintaining the linter’s configuration files is laborious

Keeping a document with the company’s rules requires dedication as new versions of the programming language or framework comes out. What engineering teams always neglect is that style guides get obsolete as people leave and join the company as well.

In small or mid-sized teams, when you hire opinionated engineers or fire senior developers, there are great chances that old discussions emerge again. As changing documentation is harder, linters’ configuration files differ from the predefined styles.

The same occurs with code documentation, which always ends up in the question: is it outdated documentation or an implementation bug?

Taking as an example the Airbnb JavaScript style guide, you can notice the documentation ships with some linters files already configured, which saves time and enforces consistency between the style guide documentation and how it performs the checks.

Faster ramp up of new-hires

If your company adopts a specific style guide with lots of custom rules for linters, then the ramp-up of new-hires is slower. The same may apply if different teams adopt different code conventions — which sounds against the idea of standardization of the code. The uniqueness of the settings increases the cognitive demand for new-hires during onboarding.

It means that adopting a community-maintained style guide helps scaling companies. In fact, I strongly recommend choosing a style guide before growing fast, as the coordination efforts of doing it afterward is significantly higher.

When you use the Airbnb, Standard, Idiomatic or whatever JavaScript style guide, the adherence to them will probably be higher than understanding and promoting your company’s own. Many of the hired engineers may already know the rules by heart, which accelerates the ramp up.

Feedback comes from the community

Prefer a community-based solution over a custom implementation. That’s what I believe is the best for companies I worked for, and what I always foster as part of SourceLevel’s culture.

Besides all the open-source benefits, the strongest point of adopting an open-source style guide is getting external feedback. Otherwise, the team relies only on their experience. The external view brings more value to the discussion.

If you the team really has strong arguments on a certain preference, the repository is open-source, and will accept a pull request or issue for discussing the matter. Of course, you can’t take the change as granted. But you definitively can collaborate with the community by sharing your opinions. And this is the kind of environment I want to promote.

Few exceptions

I think there are few exceptions to the rule. If your company is big enough, or maybe has created a framework that became very popular, then you might consider creating a public style guide. The community can help in the process, and it is a win-win.

This rule applies to big open-source projects as well. After establishing the rules for that project, it can be used by other people and companies around the world. However, if you don’t intend to put effort into maintaining it, I’d simply adopt an existing style guide.

The post Why you should adopt a community-maintained javascript style guide appeared first on SourceLevel.

On the Four Key DevOps Metrics, and why I measure them differently

George Guimarães — Fri, 06 Nov 2020 18:21:03 +0000

The four key DevOps metrics are an exciting set of measurements. They’re getting more and more relevant since the book Accelerate has been published. I firmly believe they’re essential for engineering teams seeking effectiveness and efficiency.

The Four key DevOps metrics are:

Lead Time for Change
Deploy Frequency
Change Failure Rate
Median Time to Restore (MTTR)

You can learn more about measuring it in Paul Duvall’s article or reading the 2019 Accelerate State of DevOps.

In this article, I want to explore why I like them and why we measure it slightly differently at Source Level. I’ll focus on the Lead Time for Change and Deploy Frequency, as I have more experience working with them.

Why are the Four Key DevOps Metrics essential for engineering teams?

The main goal of an engineering team is to add value for the customers through technology. Delivering value is abstract, and describing what it means is hard.

Sometimes value translates into a single line of code or even in a configuration change. But at other times, value translates into three months of 8-sized-team work. It happens because value perception is not attached to the work itself. It’s bound to what end-users extract from the running product.

That’s why measuring Story Points is useless. The team attributes a numeric value based on how much effort a given User Story or task requires. So, Story Points measures engineering performance based on their effort. And, as stated, it’s not related to the end-user perception of value.

However, Modern Software Development requires agility, and it doesn’t come from the nature of the work, such as painful features or slippery bugs. Agility comes from a smooth and sustainable process.

Some years ago, using agility and process in the same sentence would be hilarious. But agile’s core is to respond to change appropriately, and delivering more doing less is a consequence, not the goal.

That said, the Four Key DevOps metrics become the best allies of Tech Leads, Engineering Managers, and VPs of Engineering looking for efficiency. These roles require full attention to the big picture, and DevOps metrics give a perfect overview of how the system responds to daily activities.

Lead Time for Change and Deploy Frequency summarize the development pipeline, and any change in the process reflects on them. Managers should have them in their dashboards or any other accessible and accurate place.

Considerations on Lead Time for Change

Lead Time for Change measures how much time it takes for a code change to reach production. It’s crucial to measure up to production because staging or any other non-official environment won’t provide any value.

However, it raises an interesting discussion on feature toggles (or feature flags). Deploying a new feature is not the final step of the value chain if your team uses feature toggles or feature flags. Features must be enabled to add value, and so, I’d consider measuring not only Lead Time for Change but also the Lead Time to Value.

Another aspect I’d like to point is statistics. The recommendation is to calculate the Median Lead Time for Change. It outputs the value at the midpoint of a frequency distribution. In other words, half of the changes are equal or less the median. But how about the other half of the changes? They could take considerably more.

At SourceLevel, we’ve been more likely to use the 75th percentile as the default metric and keeping track of the 95th percentile as well. The 75th percentile is more comprehensive and realistic. In contrast, the 95th percentile gives us an idea of the small portion of work left out of the count and excludes the top 5% most time-consuming changes, as we consider them outliers.

Considerations on Deploy Frequency

Deploy Frequency measures how many times code changes reached production in a period. It can be measure as deploy per hour, per day, per week, per month, and so on.

It’s crucial to adjust the period properly. Saying a team deploys four times in a month sounds like a team deploys once in a week. But it may not be accurate. If the team deploys four times at the end of a month, it means the team has a different pace than deploying once a week.

If it’s usual for your team to have one or zero deploys per day, don’t measure it in days. Start measuring in weeks. Once the team starts deploying more than seven times a week, you can switch for days. Switch to shorter timeframes whenever possible, but always respecting the accuracy of the information.

In short

The Four Key DevOps Metrics are useful and give an overall idea of how the system responds to daily activities. Lead Time for Change and Deploy Frequency are much more price than Story Points and should be accessible and accurate.

Tech Leads, Engineering Managers, and VP of Engineering benefit from these metrics. Although more metrics are necessary to investigate problems, they are excellent indicators of the engineering process healthiness.

The post On the Four Key DevOps Metrics, and why I measure them differently appeared first on SourceLevel.

OKRs vs. KPIs: explanation with examples for Engineering Teams.

George Guimarães — Tue, 20 Oct 2020 22:04:32 +0000

OKRs vs. KPIs, what are the differences? That’s a common question I hear from managers of Engineering Teams. KPIs are more straightforward to explain than OKRs, which can be tricky and more complex. They don’t mean the same, although they are connected.

What are KPIs?

KPI stands for Key Performance Indicators. In other words, KPIs are a set of metrics that should give you an overview of the area or team’s performance. They need to be measurable and comparable.

If you look at many KPIs, they’re not fulfilling their purpose. Organizations should select as few as possible so that tracking the progress is possible. Besides, all the significant changes in process and company goals should impact the numbers.

Then, managing an area or a team becomes more tangible: when the KPIs show poor performance, it’s time to act. The actions taken should reflect better numbers; otherwise, managers need to find another strategy and act differently.

What are OKRs?

OKRs stands for Objective Key Results. It’s a managing methodology that is popular in Silicon Valey. It’s been widely adopted by companies and startups at scale. It’s also seen as an alternative or complement for strategic planning.

OKRs’ primary purpose is to define Objectives that must align with the business and a set of Key Results. Each Key Result needs to have a measurable number as the goal and a limit date. The limit date means that the goal should be achieved within that time frame.

What’s the difference between KPIs and OKRs?

KPIs provide an overview of the area or team for managers, whereas OKRs must focus on its future. That said, it becomes clear that KPIs are a controlling tool, and OKRs intend to change an organization’s status quo and keep track of its progress by periodic assessment meetings.

It’s crucial to have that in mind when choosing the KPIs and the OKRs. Otherwise, they become useless and can even play against business goals. Let’s see some examples of them.

Examples of OKRs and KPIs for Engineering Teams

Below there is a list of KPIs examples. However, you can find more examples in my article Software Engineering KPIs: how to choose the best fitting metrics.

Deploy Frequency : it’s a sum of the number of deploys made by day, week, or month, depending on the organization’s need. It shows how frequently the team — or area — delivers value to the final user.
Time to Merge : it measures the number of days a Pull Request remains open or under review. You can find an average or, as I prefer, see the 75th percentile of all pull requests closed in a given period. It shows how performant is the team.
Time to Recover : how much time does the application is inaccessible after an error? This metric tells a lot about how engineering teams respond to failures.

When thinking of OKRs, Engineering Teams may consider Objectives such as:

Improving the Time to Market of new features
Lessen the Churn rate of the product

Here are some possible Key Results for Improving the Time to Market of new features :

Increase the Deploy Frequency to 37/week until . Assuming you deploy less than 37 times a week currently, increasing the frequency means you’re delivering more. Delivering more is crucial to achieving a more competitive Time to Market.
Reduce the 75th percentile of Time to Merge to 3 days until . Instead of the Median or Average, I prefer using the 75th percentile for Key Results. In other words, it means that 75% of the Pull Requests must be merged up to 3 days after they were opened. The team can achieve it by opening lighter pull requests or engaging in collaborators’ pull requests instead of working on a new work item.

For the second object, Lessen the Churn rate of the product , let’s assume you know the primary source of churn comes due to a high number of errors in the application. Then, the Key Results could include:

Reduce the number of Technical Debts to 15 until . Let’s say you have 30 Technical Debts currently. It’s a 50% improvement. There are many chances that improving the codebase will positively affect the churn rate and help in the KR of the previous Objective. The cleaner the code, the better it embraces the changes. It means you can reduce the churn and also achieve better Time to Market by gardening your codebase.
Reduce the Mean Time to Recover to Recover (MTTR) to 3 minutes until . The team needs to monitor application outages, connectivity problems, 503 errors, and other failures to ensure end-users’ experience is not impacted with more than 3 minutes of instability.

In short,

KPIs and OKRs are not the same. They have different purposes. KPIs aim to give managers an overview of how the team or area is working, whereas OKRs focus on providing the team a direction and then tracking its progress.

I presented some examples of KPIs and OKRs for Engineering Teams to illustrate the difference. SourceLevel provides lots of metrics, which may include your KPIs. Check out our Analytics feature, or schedule a demo with me.

If you need to define KPIs for your team, I am giving away a 30-min consultation meeting. Schedule a demo so that we can discuss your specific needs.

The post OKRs vs. KPIs: explanation with examples for Engineering Teams. appeared first on SourceLevel.

DEV Community: SourceLevel

Mastering Git: The lesser-known commands you could be using (or not)

git switch: a fresh approach to branch management

git bisect: tracking bugs down

git notes: Enhancing Commit Context

Adding Notes to Commits

Removing Notes

Listing and Viewing Notes

Sharing Diffs: git diff + git apply

Embrace Unfamiliar Commands

The Perfect Git Commit Quest

The Importance of Writing a Good Commit Message

Commit Title/Header/Subject

Using Conventional Commits

Commit Body

Commit message conventions (Annotations)

Co-authored-by

When to Commit?

Staging the Changes

Forgot Something in the Previous Commit?

The Art of Summarize: Drafting/Opening a Pull Request

Tuning Your git Command

Use Templates for Commit Messages

The Journey to Better Commits: Level Up! Quest Completed!

Creating Code Reviews opportunities

Finding Time Slots - Optimizing Your Review Routine

Using Interruptions to Your Advantage

Maximizing Collaboration: Pair Programming's Hidden Gem - Code Reviews

Empowering Psychological Safety in Code Review Discussions

Optimizing Code Reviews with Available Tools

Fostering Accountability through Code Reviews

Embrace a Strong Code Review Culture

Sunsetting SourceLevel’s Automated Code Review feature: What’s next?

RuboCop: How to install and configure

Installation

Configuration

Usage

Autocorrecting

Integrating with other tools

State of Golang linters and the differences between them

What is a linter?

First things first: how do linters analyze code?

Lexer

Parser

Golang packages

Code Formatting

Simplify option

Check unused imports

Code Complexity

ABC Metrics

Cyclomatic Complexity

Style and Patterns Checking

Golint vs Staticcheck vs revive

Testing revive linter

What else?

Where to start?

3 better Engineering Metrics uses for Managers

Metrics to motivate the team

Metrics as indicators

Experimentation and innovation

In short

Three signs your team needs Engineering Metrics ASAP

#1 — You don’t know in which step of the product delivery bottleneck is.

#2 — You don’t have any metric to report upwards.

#3 — You don’t know whether the team is making progress towards desired outcomes.

Do you want to know more about Engineering Metrics?

3 Benefits of DevOps Metrics within Engineering Teams

Benefit #1 — They consider only the engineering scope.

Benefit #2 — It promotes collaboration and alignment.

Benefit #3 — Improving the system is more effective.

You’ll probably need more metrics later.

In short

Why you should adopt a community-maintained javascript style guide

Maintaining a style guide is time-consuming

Maintaining the linter’s configuration files is laborious

Faster ramp up of new-hires

Feedback comes from the community

Few exceptions

On the Four Key DevOps Metrics, and why I measure them differently

Why are the Four Key DevOps Metrics essential for engineering teams?

`git switch`: a fresh approach to branch management

`git bisect`: tracking bugs down

`git notes`: Enhancing Commit Context

Sharing Diffs: `git diff` + `git apply`

`Co-authored-by`

Tuning Your `git` Command