Skip to content

Commit

Permalink
all: replace ’ with '
Browse files Browse the repository at this point in the history
It isn't rendering correctly on our site.

Generated with

  fastmod '’' "'" --iglob '*.md*'
  • Loading branch information
keegancsmith committed Jan 16, 2025
1 parent 793a7e4 commit f2cfba9
Show file tree
Hide file tree
Showing 394 changed files with 4,062 additions and 4,062 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -22,63 +22,63 @@ There are many benefits to contributing to a popular open source project like Do

But getting started on a new codebase can be daunting. Docker has many, many lines of code. Fixing even the smallest issue can require reading through a lot of that code and understanding how the pieces all fit together.

But its also not as difficult as you might think. You can follow [Dockers Contributor guide](http://docs.docker.com/project/who-written-for/) to get a development environment set up. Then follow these **5 simple steps to dive into a new codebase**. The skills you hone doing so will come in handy on every new project you encounter over the course of your programming life. So what are you waiting for? Here they are:
But it's also not as difficult as you might think. You can follow [Docker's Contributor guide](http://docs.docker.com/project/who-written-for/) to get a development environment set up. Then follow these **5 simple steps to dive into a new codebase**. The skills you hone doing so will come in handy on every new project you encounter over the course of your programming life. So what are you waiting for? Here they are:

### Step 1: Start at func main()

Start with what you know, as the old saying goes. If youre like most Docker users, you probably mainly use the Docker CLI. So lets start with the entry point into that program: the [main function](https://sourcegraph.com/github.com/docker/docker@master/.GoPackage/github.com/docker/docker/docker/.def/docker.go/main).
Start with what you know, as the old saying goes. If you're like most Docker users, you probably mainly use the Docker CLI. So let's start with the entry point into that program: the [main function](https://sourcegraph.com/github.com/docker/docker@master/.GoPackage/github.com/docker/docker/docker/.def/docker.go/main).

For the remainder of this post, well use [Sourcegraph](https://sourcegraph.com/), which the Docker team uses to search and browse code on the web as you would in an intelligent IDE. To follow along, it may be easiest to [open a second browser window to Sourcegraph](https://sourcegraph.com/) and hop back and forth between that and this post.
For the remainder of this post, we'll use [Sourcegraph](https://sourcegraph.com/), which the Docker team uses to search and browse code on the web as you would in an intelligent IDE. To follow along, it may be easiest to [open a second browser window to Sourcegraph](https://sourcegraph.com/) and hop back and forth between that and this post.

On Sourcegraph, lets go to the main [func main()](https://sourcegraph.com/github.com/docker/docker/-/def/GoPackage/github.com/docker/docker/cmd/docker/-/docker.go/main) inside the [Docker repository](https://sourcegraph.com/github.com/docker/docker).
On Sourcegraph, let's go to the main [func main()](https://sourcegraph.com/github.com/docker/docker/-/def/GoPackage/github.com/docker/docker/cmd/docker/-/docker.go/main) inside the [Docker repository](https://sourcegraph.com/github.com/docker/docker).

At the top of the main function, we see a lot of code related to setting up logging, reading command flags, and initializing defaults. At the bottom, we find a call to [client.NewDockerCli](https://sourcegraph.com/github.com/docker/docker/-/def/GoPackage/github.com/docker/docker/api/client/-/NewDockerCli), which seems to be responsible for creating the struct whose methods do all the actual work. Lets [issue a search query for NewDockerCli](https://sourcegraph.com/github.com/docker/docker?q=newdockercli).
At the top of the main function, we see a lot of code related to setting up logging, reading command flags, and initializing defaults. At the bottom, we find a call to [client.NewDockerCli](https://sourcegraph.com/github.com/docker/docker/-/def/GoPackage/github.com/docker/docker/api/client/-/NewDockerCli), which seems to be responsible for creating the struct whose methods do all the actual work. Let's [issue a search query for NewDockerCli](https://sourcegraph.com/github.com/docker/docker?q=newdockercli).

### Step 2: Get to the core

In many applications and libraries, there's one or two key interfaces that describe the core functionality or essence. Lets try to get there from where we are now.
In many applications and libraries, there's one or two key interfaces that describe the core functionality or essence. Let's try to get there from where we are now.

Clicking on the [NewDockerCli](https://sourcegraph.com/github.com/docker/docker/-/def/GoPackage/github.com/docker/docker/api/client/-/NewDockerCli) search result, we arrive at the definition of the function. Since what were interested in is the struct that the function returns, [DockerCli](https://sourcegraph.com/github.com/docker/docker/-/def/GoPackage/github.com/docker/docker/api/client/-/DockerCli), lets click on the return type to jump to its definition.
Clicking on the [NewDockerCli](https://sourcegraph.com/github.com/docker/docker/-/def/GoPackage/github.com/docker/docker/api/client/-/NewDockerCli) search result, we arrive at the definition of the function. Since what we're interested in is the struct that the function returns, [DockerCli](https://sourcegraph.com/github.com/docker/docker/-/def/GoPackage/github.com/docker/docker/api/client/-/DockerCli), let's click on the return type to jump to its definition.

Clicking on DockerCli brings us to [its definition](https://sourcegraph.com/github.com/docker/docker/-/def/GoPackage/github.com/docker/docker/api/client/-/DockerCli). Scrolling down through this file, we see its methods, getMethod, Cmd, Subcmd, and LoadConfigFile. Cmd looks noteworthy. Its the only method with a docstring and the docstring suggests that its the core method for executing each Docker command.
Clicking on DockerCli brings us to [its definition](https://sourcegraph.com/github.com/docker/docker/-/def/GoPackage/github.com/docker/docker/api/client/-/DockerCli). Scrolling down through this file, we see its methods, getMethod, Cmd, Subcmd, and LoadConfigFile. Cmd looks noteworthy. It's the only method with a docstring and the docstring suggests that it's the core method for executing each Docker command.

### Step 3: Dive deep

Now that weve found [DockerCli](https://sourcegraph.com/github.com/docker/docker/-/def/GoPackage/github.com/docker/docker/api/client/-/DockerCli), the core “controller” of the Docker client, lets dive into how one of the specific Docker commands work. Lets zoom in on docker build.
Now that we've found [DockerCli](https://sourcegraph.com/github.com/docker/docker/-/def/GoPackage/github.com/docker/docker/api/client/-/DockerCli), the core “controller” of the Docker client, let's dive into how one of the specific Docker commands work. Let's zoom in on docker build.

Reading the implementation of [DockerClis Command method](https://sourcegraph.com/github.com/docker/docker/-/def/GoPackage/github.com/docker/docker/api/client/-/DockerCli/Command), we see it looks up the subcommand to invoke the corresponding function.
Reading the implementation of [DockerCli's Command method](https://sourcegraph.com/github.com/docker/docker/-/def/GoPackage/github.com/docker/docker/api/client/-/DockerCli/Command), we see it looks up the subcommand to invoke the corresponding function.

So, in the case of “docker build”, it calls the [CmdBuild](https://sourcegraph.com/github.com/docker/docker/-/def/GoPackage/github.com/docker/docker/api/client/-/DockerCli/CmdBuild) method, which we can navigate to using Sourcegraph.

There's a lot going on here. At the top of the method, we see code dealing with a variety of input methods for the Dockerfile and configuration. Oftentimes, a good strategy for reading through a long method is to work backwards. Start at the bottom and look at what the method does at the very end. In many cases, thats the meat of the method and everything before is just setup for completing that core action.
There's a lot going on here. At the top of the method, we see code dealing with a variety of input methods for the Dockerfile and configuration. Oftentimes, a good strategy for reading through a long method is to work backwards. Start at the bottom and look at what the method does at the very end. In many cases, that's the meat of the method and everything before is just setup for completing that core action.

Now that weve understood a single Docker client command through and through, you might be interested in diving deeper still and finding where the daemon receives the request and following it all the way down to its interaction with LXC and the kernel. Thats certainly a valid route, but we leave that for now as an exercise to the reader. Instead, lets get a broader understanding of the key components of the client.
Now that we've understood a single Docker client command through and through, you might be interested in diving deeper still and finding where the daemon receives the request and following it all the way down to its interaction with LXC and the kernel. That's certainly a valid route, but we leave that for now as an exercise to the reader. Instead, let's get a broader understanding of the key components of the client.

### Step 4: Look at usage examples

One way of better understanding a piece of code is to look at usage examples of how that code is used. Lets go back to the [CmdBuild](https://sourcegraph.com/github.com/docker/docker/-/def/GoPackage/github.com/docker/docker/api/client/-/DockerCli/CmdBuild) method and click on the call to the [addTrustedFlags](https://sourcegraph.com/github.com/docker/docker/-/def/GoPackage/github.com/docker/docker/api/client/-/addTrustedFlags) func.
One way of better understanding a piece of code is to look at usage examples of how that code is used. Let's go back to the [CmdBuild](https://sourcegraph.com/github.com/docker/docker/-/def/GoPackage/github.com/docker/docker/api/client/-/DockerCli/CmdBuild) method and click on the call to the [addTrustedFlags](https://sourcegraph.com/github.com/docker/docker/-/def/GoPackage/github.com/docker/docker/api/client/-/addTrustedFlags) func.

![1*tBX0RwBYWxD1pPBRw6j8vQ](//images.contentful.com/le3mxztn6yoo/47OGxPo0EMqok4IyUumkkI/72e0297483475f7a13380d01ed357313/1_tBX0RwBYWxD1pPBRw6j8vQ.png)

In order to fully understand a piece of code, you need to understand both how it works and how its used. Jumping to definition lets us understand the former by walking “forward” along the graph of code, while looking at usage examples covers the latter by walking “backward”.
In order to fully understand a piece of code, you need to understand both how it works and how it's used. Jumping to definition lets us understand the former by walking “forward” along the graph of code, while looking at usage examples covers the latter by walking “backward”.

Click on the “Used in 1 repository” text to go to the [detail page for addTrustedFlags](https://sourcegraph.com/github.com/docker/docker/-/info/GoPackage/github.com/docker/docker/api/client/-/addTrustedFlags). Here, you can see where its being called:
Click on the “Used in 1 repository” text to go to the [detail page for addTrustedFlags](https://sourcegraph.com/github.com/docker/docker/-/info/GoPackage/github.com/docker/docker/api/client/-/addTrustedFlags). Here, you can see where it's being called:

![1*XO7sOqUxUnqjGCnGdACmKg](//images.contentful.com/le3mxztn6yoo/1tvwbX52duCkgI0i8QsEEe/4b6c9f0415bf8bb0a3e562d0fd144a7a/1_XO7sOqUxUnqjGCnGdACmKg.png)

Try this out for a few more functions and methods to understand how theyre interconnected. If its helpful, draw a picture of how various components of the application interact with one another.
Try this out for a few more functions and methods to understand how they're interconnected. If it's helpful, draw a picture of how various components of the application interact with one another.

### Step 5: Select an issue and start coding!

Now that you have a decent picture of the Docker codebase as a whole, take a look at the [issue tracker](https://github.com/docker/docker/issues) to see what needs working on, and reach out to members of the Docker community with questions you arent able to answer yourself. Because you've taken the time to explore and understand the code, youll be better equipped to ask smart questions and know where specific issues fit into the broader picture.
Now that you have a decent picture of the Docker codebase as a whole, take a look at the [issue tracker](https://github.com/docker/docker/issues) to see what needs working on, and reach out to members of the Docker community with questions you aren't able to answer yourself. Because you've taken the time to explore and understand the code, you'll be better equipped to ask smart questions and know where specific issues fit into the broader picture.

And if you feel up for it, take notes along the way, document your experience, and write it up as a blog post like this one. The Docker team would love to hear about your experience diving into their code.

### Contributing effectively

One of the misconceptions that often prevents people from getting involved in projects is being daunted by the task of jumping into a large, foreign codebase. We often assume, as programmers, that the hard work lies in _writing code_, but often, its reading and understanding other peoples code that is the critical first step. Recognizing that and approaching the task in a principled way, armed with good tools for doing so, will help you conquer the psychological barrier of diving into the code.
One of the misconceptions that often prevents people from getting involved in projects is being daunted by the task of jumping into a large, foreign codebase. We often assume, as programmers, that the hard work lies in _writing code_, but often, it's reading and understanding other people's code that is the critical first step. Recognizing that and approaching the task in a principled way, armed with good tools for doing so, will help you conquer the psychological barrier of diving into the code.

So make the leap and [check out Dockers source today](https://sourcegraph.com/github.com/docker/docker). A vibrant open source community and codebase awaits you!
So make the leap and [check out Docker's source today](https://sourcegraph.com/github.com/docker/docker). A vibrant open source community and codebase awaits you!

### About the author

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ published: true

She tells the story of Matt, a fifth grade history teacher who wrote some bacon-related code in Swift

Lynns daughter has been coding since age 8 and taught Matt how to code.
Lynn's daughter has been coding since age 8 and taught Matt how to code.

Matt now teaches Java to 8th graders.

Expand All @@ -40,23 +40,23 @@ These are classic characteristics of an ideal Denial of Service attack scenarios

At one point, Jason was spending all his time answering GitHub Issues instead of building new features.

An obvious solution was just to spend less time on Issues, but thats bad, because users feel ignored and post mean memes to your project.
An obvious solution was just to spend less time on Issues, but that's bad, because users feel ignored and post mean memes to your project.

An better strategy is to ask for clarification instead of trying to guess what an issue reporter is trying to say. “Can you elaborate? What did you mean by X?” This doesn't take a lot of your time, but shows that you are super responsive.

Asking for clarification tells a user you are responsive to their needs, so they will in turn reciprocate by investing time into composing a more detailed description of their issue. If youre lucky, they may even end up answering their own questions.
Asking for clarification tells a user you are responsive to their needs, so they will in turn reciprocate by investing time into composing a more detailed description of their issue. If you're lucky, they may even end up answering their own questions.

So if youre unclear about something, “just ask for clarifications.”
So if you're unclear about something, “just ask for clarifications.”

### Gregor Martynus of hood.ie: Growing a healthy community by dedicating space ([slides](https://github.com/sourcegraph/github-universe-2016-slides/blob/master/Dedicating%20Space%20-%20Gregor%20Martynus.pdf))

![1*vf4MwOFzzPi6E7toYsNPgA](//images.contentful.com/le3mxztn6yoo/4oVRvkLXKosysmQM0QI08O/28a783848fceea93c4ca143dda2c184c/1_vf4MwOFzzPi6E7toYsNPgA.jpeg)

How can you get more people to become active contributors to your project?

Thanks to GitHub, collaborating on code is easier than ever. But open source is intimidating. Lack of tooling is no longer the bottleneck. People issues are. If you arent good at fostering an inclusive, welcoming culture, youre missing out on great potential contributors.
Thanks to GitHub, collaborating on code is easier than ever. But open source is intimidating. Lack of tooling is no longer the bottleneck. People issues are. If you aren't good at fostering an inclusive, welcoming culture, you're missing out on great potential contributors.

Hoodie is trying to be one of open sources most diverse and inclusive communities. To foster this, they created a dedicated space for contributors and community members: [hoodie.camp](http://hoodie.camp). Its built on top of the GitHub API.
Hoodie is trying to be one of open source's most diverse and inclusive communities. To foster this, they created a dedicated space for contributors and community members: [hoodie.camp](http://hoodie.camp). It's built on top of the GitHub API.

### Bringing back open source projects to life, Enrique Mogollan, Software Engineer at Salesforce Desk

Expand All @@ -81,11 +81,11 @@ Even if a community is dormant, they can still be woken up and act as a team. Bi

![1*O9cLEjpyzkAXgqCBsLTkEA](//images.contentful.com/le3mxztn6yoo/6hf0VLR2gMcO2ySoCKk8WC/77e6591edde86e487d8c331e2a22bd1e/1_O9cLEjpyzkAXgqCBsLTkEA.jpeg)

Open source is everywhere, but change is still frightening. Imagine you've discovered a great open source project, but its still unknown to the stakeholders in your org.
Open source is everywhere, but change is still frightening. Imagine you've discovered a great open source project, but it's still unknown to the stakeholders in your org.

> Fighting for open source is a lot like Street Fighter.
How do you convince people? Its like the Street Fighter Training Room. Show, dont tell .The future is hard for people to see, so give them as many chances to interact and play around with the new thing.
How do you convince people? It's like the Street Fighter Training Room. Show, don't tell .The future is hard for people to see, so give them as many chances to interact and play around with the new thing.

**“Learn to block.”** Guard your lifebar. An open source library is going to some things well, other things poorly. Explain the tradeoffs before people point out the flaws. No solution is perfect.

Expand All @@ -95,4 +95,4 @@ How do you convince people? It’s like the Street Fighter Training Room. Show,

**“Learn to lose”** — failure is feedback. Learn from losses so you can win the next battles.

**“Its never Game Over.”** Its only over when you quit trying.
**“It's never Game Over.”** It's only over when you quit trying.
Loading

0 comments on commit f2cfba9

Please sign in to comment.