diff --git a/_data/toc.yaml b/_data/toc.yaml index 06adbef932..eea3751fd5 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -464,78 +464,10 @@ guides: - path: /compliance/cis/ title: CIS -- sectiontitle: Open source at Docker +- sectiontitle: Contributors guide section: - - path: /opensource/code/ - title: Quickstart contribution - - sectiontitle: Set up for Docker development - section: - - path: /opensource/project/who-written-for/ - title: README first - - path: /opensource/project/software-required/ - title: Get the required software - - path: /opensource/project/software-req-win/ - title: Set up for development on Windows - - path: /opensource/project/set-up-git/ - title: Configure Git for contributing - - path: /opensource/project/set-up-dev-env/ - title: Work with a development container - - path: /opensource/project/test-and-docs/ - title: Run tests and test documentation - - sectiontitle: Contribution workflow - section: - - path: /opensource/workflow/make-a-contribution/ - title: Understand how to contribute - - path: /opensource/workflow/find-an-issue/ - title: Find and claim an issue - - path: /opensource/workflow/work-issue/ - title: Work on your issue - - path: /opensource/workflow/create-pr/ - title: Create a pull request (PR) - - path: /opensource/workflow/review-pr/ - title: Participate in the PR review - - path: /opensource/workflow/advanced-contributing/ - title: Advanced contributing - - path: /opensource/workflow/coding-style/ - title: Coding style checklist - - sectiontitle: Other ways to contribute - section: - - path: /opensource/ways/meetups/ - title: Organize a Docker meetup - - path: /opensource/ways/issues/ - title: Organize our issues - - path: /opensource/ways/community/ - title: Support the community - - path: /opensource/ways/test/ - title: Testing contributions - - sectiontitle: Contribute to Kitematic - section: - - path: /opensource/kitematic/get_started/ - title: Get started - - path: /opensource/kitematic/find_issue/ - title: Find an issue - - path: /opensource/kitematic/set_up_dev/ - title: Set up for Kitematic development - - path: /opensource/kitematic/work_issue/ - title: Develop in Kitematic (work on an issue) - - path: /opensource/kitematic/create_pr/ - title: Create a pull request (PR) - - path: /opensource/kitematic/next_steps/ - title: Where to learn more - - sectiontitle: Governance - section: - - path: /opensource/governance/dgab-info/ - title: Docker governance advisory board - - path: /opensource/governance/board-profiles/ - title: Board member profiles - - path: /opensource/governance/conduct-code/ - title: Code of conduct - - path: /opensource/FAQ/ - title: FAQ for contributors - - path: /opensource/get-help/ - title: Where to chat or get help - - path: /opensource/doc-style/ - title: Style guide for Docker documentation + - path: /opensource/ + title: Contribute to the documentation - sectiontitle: section: - path: /docsarchive/ diff --git a/opensource/FAQ.md b/opensource/FAQ.md deleted file mode 100644 index 078623e91c..0000000000 --- a/opensource/FAQ.md +++ /dev/null @@ -1,153 +0,0 @@ ---- -description: Overview of contributing -keywords: open, source, contributing, overview -title: FAQ for contributors ---- - -This section contains some frequently asked questions and tips for -troubleshooting problems in your code contribution. - -- [How do I set my signature?](FAQ.md#how-do-i-set-my-signature) -- [How do I track changes from the docker repo upstream?](FAQ.md#how-do-i-track-changes-from-the-docker-repo-upstream) -- [How do I format my Go code?](FAQ.md#how-do-i-format-my-go-code) -- [What is the pre-pull request checklist?](FAQ.md#what-is-the-pre-pull-request-checklist) -- [How should I comment my code?](FAQ.md#how-should-i-comment-my-code) -- [How do I rebase my feature branch?](FAQ.md#how-do-i-rebase-my-feature-branch) - -## How do I set my signature? - -1. Change to the root of your `docker-fork` repository. - - ``` - $ cd docker-fork - ``` - -2. Set your `user.name` for the repository. - - ``` - $ git config --local user.name "FirstName LastName" - ``` - -3. Set your `user.email` for the repository. - - ``` - $ git config --local user.email "emailname@mycompany.com" - ``` - -## How do I track changes from the docker repo upstream? - -Set your local repo to track changes upstream, on the `docker` repository. - -1. Change to the root of your Docker repository. - - ``` - $ cd docker-fork - ``` - -2. Add a remote called `upstream` that points to `docker/docker`. - - ``` - $ git remote add upstream https://github.com/moby/moby.git - ``` - -## How do I format my Go code? - -Run `gofmt -s -w filename.go` on each changed file before committing your changes. -Most [editors have plug-ins](https://github.com/golang/go/wiki/IDEsAndTextEditorPlugins) that do the formatting automatically. - -## What is the pre-pull request checklist? - -* Sync and cleanly rebase on top of Docker's `master`; do not mix multiple branches - in the pull request. - -* Squash your commits into logical units of work using - `git rebase -i` and `git push -f`. - -* If your code requires a change to tests or documentation, include code, test, -and documentation changes in the same commit as your code; this ensures a -revert would remove all traces of the feature or fix. - -* Reference each issue in your pull request description (`#XXXX`). - -## How should I comment my code? - -The Go blog wrote about code comments, it is a single page explanation. A summary follows: - -- Comments begin with two forward `//` slashes. -- To document a type, variable, constant, function, or even a package, write a -regular comment directly preceding the elements declaration, with no intervening blank -line. -- Comments on package declarations should provide general package documentation. -- For packages that need large amounts of introductory documentation: the -package comment is placed in its own file. -- Subsequent lines of text are considered part of the same paragraph; you must -leave a blank line to separate paragraphs. -- Indent pre-formatted text relative to the surrounding comment text (see gob's doc.go for an example). -- URLs are converted to HTML links; no special markup is necessary. - -## How do I rebase my feature branch? - -Always rebase and squash your commits before making a pull request. - -1. Fetch any of the last minute changes from `docker/docker`. - - ``` - $ git fetch upstream master - ``` - -3. Start an interactive rebase. - - ``` - $ git rebase -i upstream/master - ``` - -4. Rebase opens an editor with a list of commits. - - ``` - pick 1a79f55 Tweak some of images - pick 3ce07bb Add a new line - ``` - - If you run into trouble, `git --rebase abort` removes any changes and gets you -back to where you started. - -4. Replace the `pick` keyword with `squash` on all but the first commit. - - ``` - pick 1a79f55 Tweak some of images - squash 3ce07bb Add a new line - ```` - - After closing the file, `git` opens your editor again to edit the commit - message. - -5. Edit and save your commit message. - - ``` - $ git commit -s - ``` - - Make sure your message includes your signature. - -8. Push any changes to your fork on GitHub, using the `-f` option to -force the previous change to be overwritten. - - ``` - $ git push -f origin my-keen-feature - ``` - -## How do I update vendor package from upstream? - -1. If you are not using the development container, download the - [vndr](https://github.com/LK4D4/vndr) vendoring tool. The `vndr` - tool is included in the development container. - -2. Edit the package version in `vendor.conf` to use the package you want to use, such as - `github.com/gorilla/mux`. - -3. Run `vndr `. For example: - - ```bash - vndr github.com/gorilla/mux - ``` diff --git a/opensource/code.md b/opensource/code.md deleted file mode 100644 index 59f0a4d4d3..0000000000 --- a/opensource/code.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -description: Contribute code -keywords: governance, open source, opensource, contributions, code, pull requests -redirect_from: -- /contributing/contributing -title: Quickstart code contribution ---- - -If you'd like to improve the code of any of Docker's projects, we would love to -have your contributions. All of our projects' code repositories are on -[Github](https://github.com/docker){: target="_blank" class="_"}. - -If you want to contribute to the `moby/moby` repository you should be familiar -with or interested in learning Go. If you know other languages, investigate our -other repositories—not all of them run on Go. - -# Code contribution workflow - -Below is the general workflow for contributing Docker code. If you are an -experienced open source contributor you may be familiar with this workflow. If -you are new or just need reminders, the steps below link to more detailed -documentation in Docker's project contribution guide. - -1. [Get the software](/opensource/project/software-required/){: target="_blank" class="_"} - you need. - - This explains how to install a couple of tools used in our development - environment. What you need (or don't need) might surprise you. - -2. [Configure Git and fork the repo](/opensource/project/set-up-git/){: target="_blank" class="_"}. - - Your Git configuration can make it easier for you to contribute. - Configuration is especially key if you are new to contributing or to Docker. - -3. [Learn to work with the Docker development container](/opensource/project/set-up-dev-env/){: target="_blank" class="_"}. - - Docker developers run `docker` in `docker`. If you are a geek, this is a - pretty cool experience. - -4. [Claim an issue](/opensource/workflow/find-an-issue/){: target="_blank" class="_"}. - - We created a [filter](http://goo.gl/Hsp2mk){: target="_blank" class="_"} - listing all open and unclaimed issues for Docker. - -5. [Work on the issue](/opensource/workflow/work-issue/){: target="_blank" class="_"}. - - If you change or add code or docs to a project, you should test your changes - as you work. This page explains - [how to test in our development environment](/opensource/project/test-and-docs/){: target="_blank" class="_"}. - - Also, remember to always **sign your commits** as you work! To sign your - commits, include the `-s` flag in your commit like this: - - ```bash - $ git commit -s -m "Add commit with signature example" - ``` - - If you don't sign, [Gordon](https://twitter.com/gordontheturtle){: target="_blank" class="_"} - will remind you! - - -6. [Create a pull request](/opensource/workflow/create-pr){: target="_blank" class="_"}. - - If you make a change to fix an issue, add reference to the issue in the pull - request. Here is an example of a perfect pull request with a good description, - issue reference, and signature in the commit: - - ![Sign commits and issues](images/bonus.png) - - We also have checklist that describes - [what each pull request needs](FAQ.md#what-is-the-pre-pull-request-checklist). - - -7. [Participate in the pull request](/opensource/workflow/review-pr/){: target="_blank" class="_"} - until all feedback has been addressed and it's ready to merge! diff --git a/opensource/doc-style.md b/opensource/doc-style.md deleted file mode 100644 index 44aa8d3ce8..0000000000 --- a/opensource/doc-style.md +++ /dev/null @@ -1,283 +0,0 @@ ---- -description: Style guide for Docker documentation describing standards and conventions for contributors -keywords: style, guide, docker, documentation -title: Documentation style and grammar conventions ---- - -## Style standards - -Over time, different publishing communities have written standards for the style -and grammar they prefer in their publications. These standards are called -[style guides](http://en.wikipedia.org/wiki/Style_guide). Generally, Docker’s -documentation uses the standards described in the -[Associated Press's (AP) style guide](http://en.wikipedia.org/wiki/AP_Stylebook). -If a question about syntactical, grammatical, or lexical practice comes up, -refer to the AP guide first. If you don’t have a copy of (or online subscription -to) the AP guide, you can almost always find an answer to a specific question by -searching the web. If you can’t find an answer, please ask a -[maintainer](https://github.com/moby/moby/blob/master/MAINTAINERS) and -we will find the answer. - -That said, please don't get too hung up on using correct style. We'd rather have -you submit good information that doesn't conform to the guide than no -information at all. Docker's tech writers are always happy to help you with the -prose, and we promise not to judge or use a red pen! - -> **Note**: -> The documentation is written with paragraphs wrapped at 80 column lines to -> make it easier for terminal use. You can probably set up your favorite text -> editor to do this automatically for you. - -### Prose style - -In general, try to write simple, declarative prose. We prefer short, -single-clause sentences and brief three-to-five sentence paragraphs. Try to -choose vocabulary that is straightforward and precise. Avoid creating new terms, -using obscure terms or, in particular, using a lot of jargon. For example, use -"use" instead of leveraging "leverage". - -That said, don’t feel like you have to write for localization or for -English-as-a-second-language (ESL) speakers specifically. Assume you are writing -for an ordinary speaker of English with a basic university education. If your -prose is simple, clear, and straightforward it will translate readily. - -One way to think about this is to assume Docker’s users are generally university -educated and read at least a "16th" grade level (meaning they have a -university degree). You can use a -[readability tester](https://readable.io/) to help guide your judgment. For -example, the readability score for the phrase "Containers should be ephemeral" -is around the 13th grade level (first year at university), and so is acceptable. - -In all cases, we prefer clear, concise communication over stilted, formal -language. Don't feel like you have to write documentation that "sounds like -technical writing." - -### Metaphor and figurative language - -One exception to the "don’t write directly for ESL" rule is to avoid the use of -metaphor or other -[figurative language](http://en.wikipedia.org/wiki/Literal_and_figurative_language) to -describe things. There are too many cultural and social issues that can prevent -a reader from correctly interpreting a metaphor. - -## Specific conventions - -Below are some specific recommendations (and a few deviations) from AP style -that we use in our docs. - -### Contractions - -As long as your prose does not become too slangy or informal, it's perfectly -acceptable to use contractions in our documentation. Make sure to use -apostrophes correctly. - -### Use of dashes in a sentence. - -Dashes refers to the en dash (–) and the em dash (—). Dashes can be used to -separate parenthetical material. - -Usage Example: This is an example of a Docker client – which uses the Big Widget -to run – and does x, y, and z. - -Use dashes cautiously and consider whether commas or parentheses would work just -as well. We always emphasize short, succinct sentences. - -More info from the always handy [Grammar Girl site](http://www.quickanddirtytips.com/education/grammar/dashes-parentheses-and-commas). - -### Pronouns - -It's okay to use first and second person pronouns, especially if it lets you avoid a passive construction. Specifically, always use "we" to -refer to Docker and "you" to refer to the user. For example, "We built the -`exec` command so you can resize a TTY session." That said, in general, try to write simple, imperative sentences that avoid the use of pronouns altogether. Say "Now, enter your SSH key" rather than "You can now enter your SSH key." - -As much as possible, avoid using gendered pronouns ("he" and "she", etc.). -Either recast the sentence so the pronoun is not needed or, less preferably, -use "they" instead. If you absolutely can't get around using a gendered pronoun, -pick one and stick to it. Which one you choose is up to you. One common -convention is to use the pronoun of the author's gender, but if you prefer to -default to "he" or "she", that's fine too. - -### Capitalization - -#### In general - -Only proper nouns should be capitalized in body text. In general, strive to be -as strict as possible in applying this rule. Avoid using capitals for emphasis -or to denote "specialness". - -The word "Docker" should always be capitalized when referring to either the -company or the technology. The only exception is when the term appears in a code -sample. - -#### Starting sentences - -Because code samples should always be written exactly as they would appear -on-screen, you should avoid starting sentences with a code sample. - -#### In headings - -Headings take sentence capitalization, meaning that only the first letter is -capitalized (and words that would normally be capitalized in a sentence, e.g., -"Docker"). Do not use Title Case (i.e., capitalizing every word) for headings. Generally, we adhere to [AP style -for titles](http://www.quickanddirtytips.com/education/grammar/capitalizing-titles). - -### Periods - -We prefer one space after a period at the end of a sentence, not two. - -See [lists](doc-style.md#lists) below for how to punctuate list items. - -### Abbreviations and acronyms - -* Exempli gratia (e.g.) and id est (i.e.): these should always have periods and -are always followed by a comma. - -* Acronyms are pluralized by simply adding "s", e.g., PCs, OSs. - -* On first use on a given page, the complete term should be used, with the -abbreviation or acronym in parentheses. E.g., Red Hat Enterprise Linux (RHEL). -The exception is common, non-technical acronyms like AKA or ASAP. Note that -acronyms other than i.e. and e.g. are capitalized. - -* Other than "e.g." and "i.e." (as discussed above), acronyms do not take -periods, PC not P.C. - - -### Lists - -When writing lists, keep the following in mind: - -Use bullets when the items being listed are independent of each other and the -order of presentation is not important. - -Use numbers for steps that have to happen in order or if you have mentioned the -list in introductory text. For example, if you wrote "There are three config -settings available for SSL, as follows:", you would number each config setting -in the subsequent list. - -In all lists, if an item is a complete sentence, it should end with a -period. Otherwise, we prefer no terminal punctuation for list items. -Each item in a list should start with a capital. - -### Numbers - -Write out numbers in body text and titles from one to ten. From 11 on, use numerals. - -### Notes - -Use notes sparingly and only to bring things to the reader's attention that are -critical or otherwise deserving of being called out from the body text. Please -format all notes as follows: - - > **Note**: - > One line of note text - > another line of note text - -### Avoid excess use of "i.e." - -Minimize your use of "i.e.". It can add an unnecessary interpretive burden on -the reader. Avoid writing "This is a thing, i.e., it is like this". Just -say what it is: "This thing is …" - -### Preferred usages - -#### Login vs. log in. - -A "login" is a noun (one word), as in "Enter your login". "Log in" is a compound -verb (two words), as in "Log in to the terminal". - -### Oxford comma - -One way in which we differ from AP style is that Docker’s docs use the [Oxford -comma](http://en.wikipedia.org/wiki/Serial_comma) in all cases. That’s our -position on this controversial topic, we won't change our mind, and that’s that! - -### Code and UI text styling - -We require `code font` styling (monospace, sans-serif) for all text that refers -to a command or other input or output from the CLI. This includes file paths -(e.g., `/etc/hosts/docker.conf`). If you enclose text in backticks (\`), markdown -will style the text as code. - -Text from a CLI should be quoted verbatim, even if it contains errors or its -style contradicts this guide. You can add "(sic)" after the quote to indicate -the errors are in the quote and are not errors in our docs. - -Text taken from a GUI, such as menu text or button text, should be bold. -Use the text exactly as it appears in the GUI. For example: - -```none -Click **Continue** to save the settings. -``` - -Text that refers to a keyboard command or hotkey should be capitalized and bold. For example: **Ctrl-D**. - -When writing CLI examples, give the user hints by making the examples resemble -exactly what they see in their shell: - -* Indent shell examples by 4 spaces so they get rendered as code blocks. -* Start typed commands with `$ ` (dollar space), so that they are easily - differentiated from program output. -* Program output has no prefix. -* Comments begin with `# ` (hash space). -* In-container shell commands, begin with `$$ ` (dollar dollar space). - -Please test all code samples to ensure that they are correct and functional so -that users can successfully copy-and-paste samples directly into the CLI. - -## Pull requests - -The pull request (PR) process is in place so that we can ensure changes made to -the docs are the best changes possible. A good PR will do some or all of the -following: - -* Explain why the change is needed -* Point out potential issues or questions -* Ask for help from experts in the company or the community -* Encourage feedback from core developers and others involved in creating the - software being documented. - -Writing a PR that is singular in focus and has clear objectives will encourage -all of the above. Done correctly, the process allows reviewers (maintainers and -community members) to validate the claims of the documentation and identify -potential problems in communication or presentation. - -### Commit messages - -In order to write clear, useful commit messages, please follow these -[recommendations](http://robots.thoughtbot.com/5-useful-tips-for-a-better-commit-message). - -Please don't reference pull requests or issues by number in the commit -messages, because they will ping the original ticket every time the commit gets -pushed anywhere (even within your own fork). - -## Links - -For accessibility and usability reasons, avoid using phrases such as "click -here" for link text. Recast your sentence so that the link text describes the -content of the link, as we did in the -["Commit messages" section](doc-style.md#commit-messages) above. - -You can use relative links (../linkeditem) to link to other pages in Docker's -documentation. - -## Graphics - -When you need to add a graphic, try to make the file size as small as possible. -If you need help reducing file size of a high-resolution image, feel free to -contact us for help. -Usually, graphics should go in the same directory as the .md file that -references them, or in a subdirectory for images if one already exists. - -The preferred file format for graphics is PNG, but GIF and JPG are also -acceptable. - -If you are referring to a specific part of the UI in an image, use -call-outs (circles and arrows or lines) to highlight what you’re referring to. -Line width for call-outs should not exceed five pixels. The preferred color for -call-outs is red. - -Be sure to include descriptive alt-text for the graphic. This greatly helps -users with accessibility issues. - -Lastly, be sure you have permission to use any included graphics. diff --git a/opensource/get-help.md b/opensource/get-help.md deleted file mode 100644 index 461d07f927..0000000000 --- a/opensource/get-help.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -description: Describes Docker's communication channels -keywords: IRC, Google group, Twitter, blog, Stackoverflow -title: Where to chat or get help ---- - -There are several communications channels you can use to chat with Docker -community members and developers. - -| Communications channel | Description | -|-------------------------------------------------------|---------------| -| [Docker Community Forums](https://forums.docker.com/) | A great place for contributors and others working with Docker software or projects to chat and ask questions. | -| [Docker Community Slack](https://dockr.ly/community) | Chat with other Docker users, as well as Docker employees. Be sure to join the `#docs` channel! | -| [@docker on Twitter](https://twitter.com/docker/) | Follow [@docker](https://twitter.com/docker/) to get updates on our products, tweet us questions or share blogs or stories. | -| [Stack Overflow](http://stackoverflow.com/search?tab=newest&q=docker) | Docker is a [hot topic](http://stackoverflow.com/search?tab=newest&q=docker) on Stack Overflow, and Docker engineers and expert users regularly contribute to these discussions. Join the conversation! | - diff --git a/opensource/governance/board-profiles.md b/opensource/governance/board-profiles.md deleted file mode 100644 index 57ab8acef0..0000000000 --- a/opensource/governance/board-profiles.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -description: Board member profiles -keywords: governance, board, members, profiles -title: Board member profiles ---- - -The Docker Project is led by three individuals who are responsible for the direction, operations, quality and community of the project as a whole. - -### Chief Architect : Solomon Hykes - -The chief architect is responsible for the general direction of the project, -defining it’s design principles, and preserving the integrity of it’s overall -architecture as the platform grows and matures. - -### Chief Maintainer : Michael Crosby - -The chief maintainer is responsible for all aspects of quality for the project -including code reviews, usability, stability, security and performance. - -### Chief Operator : Steve Francia - -The chief operator is responsible for the day-to-day operations of the project -including: facilitating communications amongst all the contributors; tracking -release schedules; managing the relationship with downstream distributions and -upstream dependencies; and helping new contributors to get involved and become -successful contributors and maintainers. The role is also responsible for -managing and measuring the success of the overall project and ensuring it is -governed properly working in concert with the Docker Governance Advisory Board -(DGAB). - - - -# Members of the 2015 DGAB - -The DGAB is made up of 16 individual who represent the ecosystem, contributors -and community of the Docker Project. - -## Docker - -* Michael Crosby -* Steve Francia -* Stephen Day -* Arnaud Porterie - -## Individual Contributors - -* Andrew Tianon Page -* Aleksa Sarai -* Harald Albers -* Darren Shepherd - -## Corporate Contributors - -* Jeff Borek (IBM) -* Dan Walsh (RedHat) -* Ahmet Alp Balkan (Microsoft) -* Rohit Jnagal (Google) - -## Users - -* Nicola Paolucci (Atlassian) -* Burke Libbey (Shopify) -* Meghdoot Bhattacharya (PayPal) -* Tapabrata Pal (Capital One) \ No newline at end of file diff --git a/opensource/governance/conduct-code.md b/opensource/governance/conduct-code.md deleted file mode 100644 index de3fda0046..0000000000 --- a/opensource/governance/conduct-code.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -description: Explains Docker's code of conduct -keywords: Docker, conduct, code -title: Code of conduct ---- - -The Docker project has not currently adopted a Code of Conduct though there is -work being done in this regard. Without a formal Code of Conduct being adopted -by the project, it is anticipated that participants and contributors follow the -generic [contributor covenant](http://contributor-covenant.org) until a formal -code of conduct is adopted. - -# Contributor Covenant - -As contributors and maintainers of this project, we pledge to respect all people -who contribute through reporting issues, posting feature requests, updating -documentation, submitting pull requests or patches, and other activities. - -We are committed to making participation in this project a harassment-free -experience for everyone, regardless of level of experience, gender, gender -identity and expression, sexual orientation, disability, personal appearance, -body size, race, ethnicity, age, or religion. - -Examples of unacceptable behavior by participants include the use of sexual -language or imagery, derogatory comments or personal attacks, trolling, public -or private harassment, insults, or other unprofessional conduct. - -Project maintainers have the right and responsibility to remove, edit, or -reject comments, commits, code, wiki edits, issues, and other contributions -that are not aligned to this Code of Conduct. Project maintainers who do not -follow the Code of Conduct may be removed from the project team. - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by opening an issue or contacting one or more of the project -maintainers. - -This Code of Conduct is adapted from the [Contributor -Covenant](http://contributor-covenant.org), version 1.0.0, available at -[http://contributor-covenant.org/version/1/0/0/](http://contributor-covenant.org/version/1/0/0/). diff --git a/opensource/governance/dgab-info.md b/opensource/governance/dgab-info.md deleted file mode 100644 index 367e95309b..0000000000 --- a/opensource/governance/dgab-info.md +++ /dev/null @@ -1,192 +0,0 @@ ---- -description: Docker Governance Advisory Board -keywords: governance, board, members, explained -title: 'Docker Governance Advisory Board: June 2015 version' ---- - -An initial version of this proposal was posted for comments on April 30th, -2014. This version reflects all comments received prior to announcing the -initial members/nominees for the board on June 10th. This document was -updated to reflect the new membership for 2015. - -## 1.0 Background - -The Docker project is experiencing incredible momentum in project growth, -adoption, and contribution. As of June 9, 2014, there are over 460 -contributors, 95% of whom do not work for the project’s commercial sponsor. -Large numbers of projects are being built on top of or incorporating Docker -(over 7,000 projects with “Docker” in the title on GitHub), and there is a -large and growing community of users. The project was designed from the outset -to have a very open structure, including open design, open contribution, and -consistent use of tools across the project. Maintainers include both Docker, -Inc. and non-Docker Inc. employees. Given the large numbers of contributors, -users, and companies with a stake in the future of the project, the project -leadership is looking to supplement the current governance and contribution -mechanisms with an advisory board, as part of its long term commitment to open -governance. - -## 2.0 Purpose - -The primary purpose of the Docker Governance Advisory Board (DGAB) is to advise -the Docker project leadership (Leadership) on matters related to supporting the -long term governance, structure, and roadmap of the Docker project. The -following main areas are included in this charter: - -* Provide a forum for individuals, users, and companies to discuss the issues - under the DGAB purview (SCOPE) -* Provide guidance and input to Leadership, and where possible, present a - consistent and consolidated opinion from the broader Docker community -* Produce a formal, twice yearly report to the Leadership and broader Docker - community of the status of and progress made in all areas under the purview - of the DGAB. -* Promote and support the use of Docker in manner consistent with Guiding * - -### Principles of the project and the Core Criteria - -The DGAB is not: - -* Intended to serve as a governance board. The DGAB advises, but does not manage, the Docker project leadership -* Intended to replace existing mechanisms for community input, governance, or contribution -* Intended to assume a formal, fiduciary role with respect to the project. The DGAB membership will not be asked to provide funds to the project, assume liabilities with respect to the project or their activities, or assume responsibility for enforcing either trademarks or DGAB recommendations - -## 3.0 Scope - -The DGAB is expected to provide input and formal recommendations regarding the following areas: - -* Docker project long term roadmap -* Docker project policies and procedures around maintenance and contributions -* Docker project policies and procedures around intellectual property, trademark, and licensing -* Core Criteria for Docker-related project (c.f. section 7.0) -* Docker project long term governance model - -## 4.0 Meetings and Memberships - -### 4.1 General - -The DGAB will have 16 members - -* The Docker Chief Maintainer: Michael Crosby -* The Docker Chief Operator: Steve Francia -* 2 seats for the top core maintainers (Docker) -* Up to 12 additional seats: 4 corporate seats, 4 individual or small business seats, 4 “user” seats - -* No fee or sponsorship is required for membership -* The membership term will last 12 months. With the exception of the Chief Maintainer, all members can serve a maximum of two consecutive terms -* The selection process is intended to be open, transparent, and guided by objective criteria for membership. -* The DGAB shall elect a Chair and Vice Chair from amongst their members to serve a renewable 6 month term. -* The Chair or Vice-Chair shall prepare an agenda for and preside over regular meetings of the DGAB. These meetings shall occur as frequently as the DGAB determines is in the project’s best interest, but no less than quarterly -* Docker, inc. shall appoint a temporary chair to set the agenda for the first meeting and preside until the election shall occur. -* A member of the DGAB may be removed by a resolution of the DGAB supported by more than two thirds of its membership. -* The DGAB may fill any vacancy arising by removal or resignation by a simple majority vote to fill the remainder of the term of the vacating member. -* The rules of election and membership outlined in this section may be varied by a resolution of the DGAB supported by more than two thirds of its voting membership. -* All project maintainers are welcome as participants and observers at DGAB meetings - -### 4.2 Selection Process - -#### Contributors: - -Four seats will be granted to the top contributors, as measured -by non-trivial pull requests merged to master in the last 6 months. Trivial -pull requests are typos, minor document corrections, or other items that do not -require a DCO. These seats will be reserved for individual contributors who are -neither employees of Docker, Inc. nor employees of companies that hold a -corporate seat. - -#### Corporate seats: - -Nomination is restricted to companies for whom all three of -the following are true - -1. Are in the top 8 companies in terms of non-trivial pull requests merged to - master in the past six months as measured by contributions by all employees -1. Have employees as maintainers and/or make significant contributions to the - code base -1. Have committed to integrate Docker into widely used products in a manner - consistent with Core Criteria. (c.f. section 7.0) - -Once nomination has been closed, selection of corporate seats will be made by a -vote by eligible contributors. Eligible contributors are those who have had at -least one non-trivial pull request merged to master in the past six months. - -#### User seats: - -These seats are for organizations that are using Docker. To be nominated, an -organization must be using Docker in production and have published a use case. -Once nomination has been closed, selection will be made by a vote by eligible -contributors. Eligible contributors are those who have had at least one -non-trivial pull request merged to master in the past six months. - -## 5.0 Operation - -The DGAB is authorized to seek advice and counsel from other interested parties -and invited experts as appropriate - -Any outside party wishing to bring an issue before the DGAB may do so by -emailing the DGAB mailing list - -The DGAB shall provide transparent and timely reporting (through any mechanism -it deems appropriate) to the Community at large on all of its activities, -subject to the right of any individual to designate their comments and the -ensuing discussion as "in confidence," in which case the public report shall -contain only a note of the request and an agreed summary (if any) of the -substance. - -The DGAB is being formed at the discretion of the Leadership. The Leadership -alone may decide to terminate the DGAB in its sole discretion; provided -however, that the Leadership shall first consult the DGAB Chair. - -The DGAB and its members shall abide by appropriate antitrust guidelines. - -## 6.0 Open Governance Principles - -The DGAB will formulate recommendations in conjunction with the following, open governance principles - -### Open participation: - -Throughout the project, anyone should be able to participate and contribute. -All bugs and tasks will be tracked in a public tracker and all of the source -code and all of the tools needed to build it will be available under an open -license permitting unrestricted use - -### Open technical meritocracy: - -Technical merit over pride of authorship. Code -is contributed for the express purpose of advancing technologies relevant to -the project, effectively separating technology advancement from individual or -commercial intent. - -### Open design: - -Roadmaps are discussed in the open, and design receives input from all -contributors and maintainers Influence through contribution: organizations and -individuals gain influence over the project through contribution - -### IP Cleanliness: - -Steps are taken to ensure that all incoming code is legally contributed (DCOs -terms-of-use etc.), that use of approved third party libraries does not create -incompatible dependencies, and that all non-trivial commits have DCOs - -### Open Licensing: - -Code should be licensed using approved, standard, open-source licenses. (Docker is currently licensed under Apache 2.0) - -## 7.0 Core Criteria - -The DGAB will formulate a set of Core Criteria for projects and commercial -products that use the Docker trademarks - -Core Criteria will generally cover such areas as: use of standard APIs, -consistent behaviors expected of Docker containers, trademark guidelines, -provenance, upstream contribution models, and alternative distributions - -As Core Criteria will not be fully defined when the initial DGAB membership is -formulated, it is understood that there is a possibility that certain members -of the initial DGAB may not agree with the Core Criteria when they are fully -defined or may have products/offerings that are not in compliance with the Core -Criteria at the time they are finalized. In this case, the corporate members -will either agree to become compliant within a specified timeframe or else -resign their DGAB position. - -Please help us improve this draft by sending your comments and feedback to -[governance@docker.com](mailto:governance@docker.com). \ No newline at end of file diff --git a/opensource/governance/images/hackday-600px.jpg b/opensource/governance/images/hackday-600px.jpg deleted file mode 100644 index 6c48d48495..0000000000 Binary files a/opensource/governance/images/hackday-600px.jpg and /dev/null differ diff --git a/opensource/governance/index.md b/opensource/governance/index.md deleted file mode 100644 index 2ea1350f30..0000000000 --- a/opensource/governance/index.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -description: Describes Docker's communication channels -keywords: IRC, Google group, Twitter, blog, Stackoverflow -title: Governance ---- - -* [Docker Governance Advisory Board](dgab-info.md ) -* [Board member profiles](board-profiles.md ) -* [Code of conduct](conduct-code.md) \ No newline at end of file diff --git a/opensource/images/docs-site-feedback.png b/opensource/images/docs-site-feedback.png new file mode 100644 index 0000000000..ebe4d052c0 Binary files /dev/null and b/opensource/images/docs-site-feedback.png differ diff --git a/opensource/index.md b/opensource/index.md index aaeca46217..a371b06805 100644 --- a/opensource/index.md +++ b/opensource/index.md @@ -1,17 +1,128 @@ --- description: Overview of contributing keywords: open, source, contributing, overview -title: Open Source at Docker +title: Contribute to documentation redirect_from: - /contributing/ - /contributing/contributing/ +- /opensource/code/ +- /opensource/project/who-written-for/ +- /opensource/project/software-required/ +- /opensource/project/software-req-win/ +- /opensource/project/set-up-git/ +- /opensource/project/set-up-dev-env/ +- /opensource/project/test-and-docs/ +- /opensource/project/who-written-for/ +- /opensource/workflow/advanced-contributing/ +- /opensource/workflow/ +- /opensource/workflow/coding-style/ +- /opensource/workflow/create-pr/ +- /opensource/workflow/find-an-issue/ +- /opensource/workflow/make-a-contribution/ +- /opensource/workflow/review-pr/ +- /opensource/workflow/work-issue/ +- /opensource/FAQ/ +- /opensource/get-help/ +- /opensource/code/ +- /opensource/doc-style/ +- /opensource/governance/ +- /opensource/governance/dgab-info/ +- /opensource/governance/board-profiles/ +- /opensource/governance/conduct-code/ +- /opensource/ways/ +- /opensource/ways/meetups/ +- /opensource/ways/issues/ +- /opensource/ways/community/ +- /opensource/ways/test/ + --- -Contributing to the Docker project or to any open source project can be a -rewarding experience. You help yourself and you help the projects you work on. -You also help the countless number of other project participants. +Contributing to the Docker documentation can be a rewarding experience. When you +offer feedback, questions, edits, or new content, you help us, the projects you +work on, and the larger Docker community. -- [Configure the development environment](project/who-written-for.md) explains how to setup an environment to contribute to Docker engine. -- [Understand the contribution workflow ](workflow/make-a-contribution.md) explains the workflow the team uses across most Docker projects. -- [Other ways to contribute](ways/index.md) provides tips for contributing if you don't want to code. -- [Governance](governance/index.md) describes the proper conduct and who defines it. \ No newline at end of file +We welcome your particpation to help make the documentation better! + +> Looking for the open source Moby project? +> +> See [Looking for Moby?](#looking-for-moby) below. + +## How to contribute to the docs + +The documentation for Docker is published at +[docs.docker.com](https://docs.docker.com/). + +There are many ways to contribute: + +- Edit, rate, or file an issue or question directly on the site by +using the links available on the right-side menu on every page +at [docs.docker.com](https://docs.docker.com/). + + ![Docs feedback links](images/docs-site-feedback.png) + +- File a documentation issue on GitHub at +[https://github.com/docker/docker.github.io/issues](https://github.com/docker/docker.github.io/issues). + + This is similar to clicking **Request doc changes** on a published docs + page, but if you manually file an issue you have to fill in links to + the related pages. + +- Fork the documentation, make changes or add new content on your local +branch, and submit a pull request (PR) to the master branch for the docs. + + This is the manual, more advanced version of clicking **Edit this page** + on a published docs page. Initiating a docs changes in a PR from your + own branch gives you more flexibility, as you can submit changes to + multiple pages or files under a single pull request, and even create + new topics. + +## Resources and guidance + +We are here to help. If you are interested in contributing, but don't feel ready +to dive in on more complex updates, we can help get you up and running. + +You might start by using the right-side menus on published pages: + +* Click **Request doc changes** on a page to automatically log an issue. + +* Click **Edit this page** to make a change to content, which automatically creates a PR. + +The issue and PR pages on GitHub give us a community space to discuss +things, and answer any questions you might have about the problem or topic you +are reporting on. + +To learn more about working on the documentation, see these topics: + +- [README on docker/docker.github.io](https://github.com/docker/docker.github.io/blob/master/README.md) + +- [Docs Test page](https://docs.docker.com/test/) - This is on the +published site. It explains how to use Docs components, resources, and +formats, and gives us a way to test and demo them. + +## Looking for Moby? + +Docker [introduced the open source Moby +project](https://blog.docker.com/2017/04/introducing-the-moby-project/) to +further promote collaboration, experimentation, and development of +container-based systems in the broader community. Moby is a library of +containerized components, a framework for assembling components into a container +platform, and tools to build, test, and deploy artifacts. It included a +reference assembly, which is the open base for the Docker platform. + +You can read about the Moby project, the open framework, components, and +relationship of Docker to Moby at [mobyproject.org](https://mobyproject.org/). + +The Moby project lives [here](https://github.com/moby/moby). + +See [Contribute to the Moby +project](https://github.com/moby/moby/blob/master/CONTRIBUTING.md) to learn how +to help work on the codebase. + +## Legacy fun and practice + +For practice with GitHub and contributing to a codebase, read through +[Contribute to Kitematic](/opensource/kitematic/index.md) which incorporates the +kind of walkthrough we originally provided as an open source contributor guide +here. See also, the [Kitematic +README](https://github.com/docker/kitematic/blob/master/README.md), and the +[Kitematic user guide](/kitematic/userguide.md). diff --git a/opensource/kitematic/find_issue.md b/opensource/kitematic/find_issue.md index 3599aaf0c3..c3479d9b55 100644 --- a/opensource/kitematic/find_issue.md +++ b/opensource/kitematic/find_issue.md @@ -10,7 +10,7 @@ display items, and integrate the updates into the codebase. To find and claim an issue you want to work on: -1. Go to the `docker/kitematic` repository. +1. Go to the [Kitematic repository](https://github.com/docker/kitematic){: target="_blank" class="_"}. 2. Click the **Issues** link. @@ -26,12 +26,14 @@ To find and claim an issue you want to work on: The comments on the issues describe the problem and can provide information for a potential solution. - For this exercise we will select the issue #1191 Missing container id. + For this exercise we will select the issue [#1191 Missing container id](https://github.com/docker/kitematic/issues/1191){: target="_blank" class="_"}. 5. When you find an open issue that both interests you and is unclaimed, add a `#dibs` comment. Make sure that no other user has chosen to work on the issue. - The project does not permit external contributors to assign issues to themselves. Read the comments to find if a user claimed the issue by leaving a `#dibs` comment on the issue. + The project does not permit external contributors to assign issues + to themselves. Read the comments to find if a user claimed the issue + by leaving a `#dibs` comment on the issue. 6. Make a note of the issue number; you will need it for later. @@ -40,4 +42,6 @@ To find and claim an issue you want to work on: Go to next section to learn [Set up your Kitematic development environment](set_up_dev.md). -(For more about working with open source issues in Docker, see Find an issue and Docker Contributing Guidelines.) \ No newline at end of file +(For more about working with open source issues, see [Contribute to the Moby +project](https://github.com/moby/moby/blob/master/CONTRIBUTING.md).{: +target="_blank" class="_"} diff --git a/opensource/kitematic/get_started.md b/opensource/kitematic/get_started.md index d41b428ab2..fb1eae3023 100644 --- a/opensource/kitematic/get_started.md +++ b/opensource/kitematic/get_started.md @@ -10,7 +10,7 @@ user interface (GUI) for working with containers. You can use Kitematic to creat ![Kitematic GUI](images/gui-splash-hub.png) -See the Kitematic user guide to learn more about it from a user perspective. +See the [Kitematic user guide](/kitematic/userguide) to learn more about it from a user perspective. ## We welcome your contributions! @@ -31,4 +31,4 @@ the Kitematic codebase, this quick tour will help you get started. Follow along ## Where to go next -[Find an issue on GitHub](find_issue.md) to get started. \ No newline at end of file +[Find an issue on GitHub](find_issue.md) to get started. diff --git a/opensource/kitematic/index.md b/opensource/kitematic/index.md index 017e8ba7d4..1546e81d27 100644 --- a/opensource/kitematic/index.md +++ b/opensource/kitematic/index.md @@ -9,4 +9,4 @@ title: Contribute to Kitematic * [Set up for Kitematic development](set_up_dev.md) * [Develop in Kitematic (work on an issue)](work_issue.md) * [Review your branch and create a pull request (PR)](create_pr.md) -* [Where to learn more](next_steps.md) \ No newline at end of file +* [Where to learn more](next_steps.md) diff --git a/opensource/kitematic/next_steps.md b/opensource/kitematic/next_steps.md index 2d7ad17150..a2528682ce 100644 --- a/opensource/kitematic/next_steps.md +++ b/opensource/kitematic/next_steps.md @@ -6,10 +6,6 @@ title: Where to learn more You've just created your first pull request to Kitematic! -The next -step is to learn how to participate in your PR's -review. - ## Take the development challenge Now that you’ve had some practice, try adding another feature to Kitematic on your own. @@ -26,12 +22,9 @@ In a terminal window, users can get this by looking at running containers with: As an exercise, implement the code changes needed to display the current container's running command. When you are ready to share the new mini feature, create a PR for it. -## Learn more about open source -To learn more about contributing to Docker open source projects, see: +## Where to go next -* - README first +- To learn more about contributing to open source projects, see +[Contribute to the Moby project](https://github.com/moby/moby/blob/master/CONTRIBUTING.md). -* Quick start contribution - -* Understand how to contribute +- To learn more about contributing to Docker product documentation, see the [README on docker/docker.github.io](https://github.com/docker/docker.github.io/blob/master/README.md) diff --git a/opensource/kitematic/set_up_dev.md b/opensource/kitematic/set_up_dev.md index ba0c4d8c12..0e782369c0 100644 --- a/opensource/kitematic/set_up_dev.md +++ b/opensource/kitematic/set_up_dev.md @@ -6,11 +6,9 @@ title: Set up for Kitematic development Kitematic is built on top of: -* Electron - -* Node.js - -* React and AltJS (which follows the Flux pattern) +- [Electron](http://electron.atom.io/){: target="_blank" class="_"} +- [Node.js](https://nodejs.org){: target="_blank" class="_"} +- [React](https://facebook.github.io/react/){: target="_blank" class="_"} and [AltJS](http://alt.js.org/){: target="_blank" class="_"} (which follows the Flux pattern). ## Download and install NVM @@ -18,8 +16,7 @@ To get started, you will need to install Node.js v4.2.1. Using Node Version Mana ### Windows: -1. Download latest release. +1. Download the [latest release](https://github.com/coreybutler/nvm-windows/releases/){: target="_blank" class="_"}. 2. Follow the installer steps to get NVM installed. Please note, you need to uninstall any existing versions of node.js before installing NVM for Windows; @@ -41,7 +38,9 @@ the above installer link will have an uninstaller available. (Alternatively, you can source nvm from your current shell with the command `. ~/.nvm/nvm.sh`.) -(To learn more about working with NVM, see macOS/Linux official nvm repo, Windows official nvm repo, and How To Install Node.js with NVM ON A VPS.) + + + To learn more about working with NVM, see the [>macOS/Linux official nvm repo](https://github.com/creationix/nvm){: target="_blank" class="_"}, the [Windows official nvm repo](https://github.com/coreybutler/nvm-windows){: target="_blank" class="_"}, and [How To Install Node.js with NVM ON A VPS](ttps://www.digitalocean.com/community/tutorials/how-to-install-node-js-with-nvm-node-version-manager-on-a-vps){: target="_blank" class="_"}. ## Install Node.js @@ -67,7 +66,7 @@ the above installer link will have an uninstaller available. To fork the master branch of Kitematic: -1. Go to the docker/kitematic repository . +1. Go to the [docker/kitematic repository](https://github.com/docker/kitematic){: target="_blank" class="_"}. 2. Click **Fork** in the upper right corner of the GitHub interface. @@ -105,7 +104,7 @@ To clone your repository and create a branch for the issue: $ git checkout -b 1191-branch ``` - As previously mentioned, issue #1191 is set up as an example to use for this exercise. + As previously mentioned, issue [#1191](https://github.com/docker/kitematic/issues/1191)is set up as an example to use for this exercise. ## Set up your signature and upstream remote @@ -135,9 +134,6 @@ You can set your signature globally or locally. $ git remote add upstream https://github.com/docker/kitematic.git ``` -(To learn more, see Set up your signature and an upstream remote.) - ## Install dependencies, start Kitematic, and verify your setup Your Node.js install includes npm for package management. You'll use it to install supporting packages and start the app. diff --git a/opensource/kitematic/work_issue.md b/opensource/kitematic/work_issue.md index 2d6e9d30a6..7869631f1a 100644 --- a/opensource/kitematic/work_issue.md +++ b/opensource/kitematic/work_issue.md @@ -4,11 +4,11 @@ keywords: Kitematic, open source, contribute, contributor, tour, development title: Develop in Kitematic (work on an issue) --- -For this tutorial, we will work on issue #1191 which is a request to display the container ID in Kitematic for easy identification. (Currently, Kitematic shows the container name but not the ID.) +For this tutorial, we will work on issue [https://github.com/docker/kitematic/issues/1191](https://github.com/docker/kitematic/issues/1191){: target="_blank" class="_"} which is a request to display the container ID in Kitematic for easy identification. (Currently, Kitematic shows the container name but not the ID.) To do this, edit the container `General Settings` layout. -1. Open the project in your favorite editor - We recommend using Atom as it's a full featured editor with great ES lint support to keep your code organized. +1. Open the project in your favorite editor - We recommend using [Atom](https://atom.io/){: target="_blank" class="_"} as it's a full featured editor with great [ES lint](http://eslint.org/){: target="_blank" class="_"} support to keep your code organized. 2. Open the `ContainerSettingsGeneral.react.js` file which is found under the `src/components/` folder and look for the following piece of code, which is in fact the layout (like HTML in the browser) circa line ~200: @@ -32,7 +32,7 @@ To do this, edit the container `General Settings` layout. ); ``` - This snippet has been saved as a GitHub gist. + This snippet has been saved as a [GitHub gist](https://gist.github.com/FrenchBen/0f514e7b3c584e8d46b5){: target="_blank" class="_"}. 4. We then need to add the variable to the rendered view, by adding it below the `{rename}` tag. The new render code should look something like: @@ -57,7 +57,7 @@ To do this, edit the container `General Settings` layout. ![Container ID](images/kitematic_gui_container_id.png) - *Note that the container ID in Kitematic matches the ID shown as output to the `docker ps` command.* + >**Note**: The container ID in Kitematic matches the ID shown as output to the `docker ps` command.* 6. You can close the Kitematic application now, and kill the running process in the terminal via Ctrl+C. @@ -73,7 +73,8 @@ To do this, edit the container `General Settings` layout. $ git commit -s -m "added container ID to show on settings tab, fixes issue #1191" ``` - (See Coding Style in the general guidelines on Contributing to Docker.) + (See the general guidelines on coding style in [Contribute to the Moby + project](https://github.com/moby/moby/blob/master/CONTRIBUTING.md){: target="_blank" class="_"}. ## Where to go next diff --git a/opensource/project/images/box.png b/opensource/project/images/box.png deleted file mode 100644 index f4990c9dad..0000000000 Binary files a/opensource/project/images/box.png and /dev/null differ diff --git a/opensource/project/images/branch-sig.png b/opensource/project/images/branch-sig.png deleted file mode 100644 index b069319eee..0000000000 Binary files a/opensource/project/images/branch-sig.png and /dev/null differ diff --git a/opensource/project/images/checked.png b/opensource/project/images/checked.png deleted file mode 100644 index 93ab2be9b3..0000000000 Binary files a/opensource/project/images/checked.png and /dev/null differ diff --git a/opensource/project/images/contributor-edit.png b/opensource/project/images/contributor-edit.png deleted file mode 100644 index d847e224a5..0000000000 Binary files a/opensource/project/images/contributor-edit.png and /dev/null differ diff --git a/opensource/project/images/copy_url.png b/opensource/project/images/copy_url.png deleted file mode 100644 index 82df4eec50..0000000000 Binary files a/opensource/project/images/copy_url.png and /dev/null differ diff --git a/opensource/project/images/existing_issue.snagproj b/opensource/project/images/existing_issue.snagproj deleted file mode 100644 index 05ae2b0ccf..0000000000 Binary files a/opensource/project/images/existing_issue.snagproj and /dev/null differ diff --git a/opensource/project/images/fork_docker.png b/opensource/project/images/fork_docker.png deleted file mode 100644 index 88c6ed8a1e..0000000000 Binary files a/opensource/project/images/fork_docker.png and /dev/null differ diff --git a/opensource/project/images/fresh_container.png b/opensource/project/images/fresh_container.png deleted file mode 100644 index 5cf875030d..0000000000 Binary files a/opensource/project/images/fresh_container.png and /dev/null differ diff --git a/opensource/project/images/git_bash.png b/opensource/project/images/git_bash.png deleted file mode 100644 index be2ec73896..0000000000 Binary files a/opensource/project/images/git_bash.png and /dev/null differ diff --git a/opensource/project/images/give_try.png b/opensource/project/images/give_try.png deleted file mode 100644 index f3f89db908..0000000000 Binary files a/opensource/project/images/give_try.png and /dev/null differ diff --git a/opensource/project/images/in_room.png b/opensource/project/images/in_room.png deleted file mode 100644 index c6c6535f7f..0000000000 Binary files a/opensource/project/images/in_room.png and /dev/null differ diff --git a/opensource/project/images/include_gcc.png b/opensource/project/images/include_gcc.png deleted file mode 100644 index b54901efa7..0000000000 Binary files a/opensource/project/images/include_gcc.png and /dev/null differ diff --git a/opensource/project/images/list_example.png b/opensource/project/images/list_example.png deleted file mode 100644 index 2e3b59a29e..0000000000 Binary files a/opensource/project/images/list_example.png and /dev/null differ diff --git a/opensource/project/images/path_variable.png b/opensource/project/images/path_variable.png deleted file mode 100644 index 99b1f453bc..0000000000 Binary files a/opensource/project/images/path_variable.png and /dev/null differ diff --git a/opensource/project/images/proposal.snagproj b/opensource/project/images/proposal.snagproj deleted file mode 100644 index c9ad49d0e7..0000000000 Binary files a/opensource/project/images/proposal.snagproj and /dev/null differ diff --git a/opensource/project/images/red_notice.png b/opensource/project/images/red_notice.png deleted file mode 100644 index 567c0a3678..0000000000 Binary files a/opensource/project/images/red_notice.png and /dev/null differ diff --git a/opensource/project/images/three_running.png b/opensource/project/images/three_running.png deleted file mode 100644 index c624ef1646..0000000000 Binary files a/opensource/project/images/three_running.png and /dev/null differ diff --git a/opensource/project/images/three_terms.png b/opensource/project/images/three_terms.png deleted file mode 100644 index 32fa84841c..0000000000 Binary files a/opensource/project/images/three_terms.png and /dev/null differ diff --git a/opensource/project/images/windows-env-vars.png b/opensource/project/images/windows-env-vars.png deleted file mode 100644 index cc932b23f1..0000000000 Binary files a/opensource/project/images/windows-env-vars.png and /dev/null differ diff --git a/opensource/project/images/windows-mingw.png b/opensource/project/images/windows-mingw.png deleted file mode 100644 index 69efbc4650..0000000000 Binary files a/opensource/project/images/windows-mingw.png and /dev/null differ diff --git a/opensource/project/index.md b/opensource/project/index.md deleted file mode 100644 index e5f7b02710..0000000000 --- a/opensource/project/index.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -description: Describes Docker's communication channels -keywords: IRC, Google group, Twitter, blog, Stackoverflow -title: Set up for Engine development ---- - - * [README first](who-written-for.md) - * [Get the required software](software-required.md) - * [Set up for development on Windows](software-req-win.md) - * [Configure Git for contributing](set-up-git.md) - * [Work with a development container](set-up-dev-env.md) - * [Run tests and test documentation](test-and-docs.md) \ No newline at end of file diff --git a/opensource/project/set-up-dev-env.md b/opensource/project/set-up-dev-env.md deleted file mode 100644 index e366df38e5..0000000000 --- a/opensource/project/set-up-dev-env.md +++ /dev/null @@ -1,330 +0,0 @@ ---- -description: How to use Docker's development environment -keywords: development, inception, container, image Dockerfile, dependencies, Go, artifacts -title: Work with a development container ---- - -In this section, you learn to develop like the Docker Engine core team. -The `docker` repository includes a `Dockerfile` at its root. This file defines -Docker's development environment. The `Dockerfile` lists the environment's -dependencies: system libraries and binaries, Go environment, Go dependencies, -etc. - -Docker's development environment is itself, ultimately a Docker container. -You use the `docker` repository and its `Dockerfile` to create a Docker image, -run a Docker container, and develop code in the container. Docker itself builds, -tests, and releases new Docker versions using this container. - -If you followed the procedures that -set up Git for contributing, you should have a fork of the `docker/docker` -repository. You also created a branch called `dry-run-test`. In this section, -you continue working with your fork on this branch. - -## Task 1. Remove images and containers - -Docker developers run the latest stable release of the Docker software. They clean their local hosts of -unnecessary Docker artifacts such as stopped containers or unused images. -Cleaning unnecessary artifacts isn't strictly necessary, but it is good -practice, so it is included here. - -To remove unnecessary artifacts: - -1. Verify that you have no unnecessary containers running on your host. - - ```none - $ docker ps -a - ``` - - You should see something similar to the following: - - ```none - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - ``` - - There are no running or stopped containers on this host. A fast way to - remove old containers is the following: - - As of Docker Engine version 1.13 you can now use the `docker system prune` command to achieve this: - - ```none - $ docker system prune -a - ``` - - Older versions of the Docker Engine should reference the command below: - - ```none - $ docker rm $(docker ps -a -q) - ``` - - This command uses `docker ps` to list all containers (`-a` flag) by numeric - IDs (`-q` flag). Then, the `docker rm` command removes the resulting list. - If you have running but unused containers, stop and then remove them with - the `docker stop` and `docker rm` commands. - -2. Verify that your host has no dangling images. - - ```none - $ docker images - ``` - - You should see something similar to the following: - - ```none - REPOSITORY TAG IMAGE ID CREATED SIZE - ``` - - This host has no images. You may have one or more _dangling_ images. A - dangling image is not used by a running container and is not an ancestor of - another image on your system. A fast way to remove dangling image is - the following: - - ```none - $ docker rmi -f $(docker images -q -a -f dangling=true) - ``` - - This command uses `docker images` to list all images (`-a` flag) by numeric - IDs (`-q` flag) and filter them to find dangling images (`-f dangling=true`). - Then, the `docker rmi` command forcibly (`-f` flag) removes - the resulting list. If you get a "docker: "rmi" requires a minimum of 1 argument." - message, that means there were no dangling images. To remove just one image, use the - `docker rmi ID` command. - -## Task 2. Start a development container - -If you followed the last procedure, your host is clean of unnecessary images and -containers. In this section, you build an image from the Engine development -environment and run it in the container. Both steps are automated for you by the -Makefile in the Engine code repository. The first time you build an image, it -can take over 15 minutes to complete. - -1. Open a terminal. - - For [Docker Toolbox](../../toolbox/overview.md) users, use `docker-machine status your_vm_name` to make sure your VM is running. You - may need to run `eval "$(docker-machine env your_vm_name)"` to initialize your - shell environment. If you use Docker for Mac 1.13 and higher, you do not need - to use Docker Machine. - -2. Change into the root of the `docker-fork` repository. - - ```none - $ cd ~/repos/docker-fork - ``` - - If you are following along with this guide, you created a `dry-run-test` - branch when you - set up Git for contributing. - -3. Ensure you are on your `dry-run-test` branch. - - ```none - $ git checkout dry-run-test - ``` - - If you get a message that the branch doesn't exist, add the `-b` flag (`git checkout -b dry-run-test`) so the - command both creates the branch and checks it out. - -4. Use `make` to build a development environment image and run it in a container. - - ```none - $ make BIND_DIR=. shell - ``` - - Using the instructions in the - `Dockerfile`, the build may need to download and / or configure source and other images. On first build this process may take between 5 - 15 minutes to create an image. The command returns informational messages as it runs. A - successful build returns a final message and opens a Bash shell into the - container. - - ```none - Successfully built 3d872560918e - docker run --rm -i --privileged -e BUILDFLAGS -e KEEPBUNDLE -e DOCKER_BUILD_GOGC -e DOCKER_BUILD_PKGS -e DOCKER_CLIENTONLY -e DOCKER_DEBUG -e DOCKER_EXPERIMENTAL -e DOCKER_GITCOMMIT -e DOCKER_GRAPHDRIVER=devicemapper -e DOCKER_INCREMENTAL_BINARY -e DOCKER_REMAP_ROOT -e DOCKER_STORAGE_OPTS -e DOCKER_USERLANDPROXY -e TESTDIRS -e TESTFLAGS -e TIMEOUT -v "home/ubuntu/repos/docker/bundles:/go/src/github.com/moby/moby/bundles" -t "docker-dev:dry-run-test" bash - root@f31fa223770f:/go/src/github.com/moby/moby# - ``` - - At this point, your prompt reflects the container's BASH shell. - -5. List the contents of the current directory (`/go/src/github.com/moby/moby`). - - You should see the image's source from the `/go/src/github.com/moby/moby` - directory. - - ![List example](images/list_example.png) - -6. Make a `docker` binary. - - ```none - root@a8b2885ab900:/go/src/github.com/moby/moby# hack/make.sh binary - ...output snipped... - bundles/1.12.0-dev already exists. Removing. - - ---> Making bundle: binary (in bundles/1.12.0-dev/binary) - Building: bundles/1.12.0-dev/binary/docker-1.12.0-dev - Created binary: bundles/1.12.0-dev/binary/docker-1.12.0-dev - Copying nested executables into bundles/1.12.0-dev/binary - ``` - -7. Run `make install`, which copies the binary to the container's - `/usr/local/bin/` directory. - - ```none - root@a8b2885ab900:/go/src/github.com/moby/moby# make install - ``` - -8. Start the Engine daemon running in the background. - - ```none - root@a8b2885ab900:/go/src/github.com/docker/docker# dockerd -D & - ...output snipped... - DEBU[0001] Registering POST, /networks/{id:.*}/connect - DEBU[0001] Registering POST, /networks/{id:.*}/disconnect - DEBU[0001] Registering DELETE, /networks/{id:.*} - INFO[0001] API listen on /var/run/docker.sock - DEBU[0003] containerd connection state change: READY - ``` - - The `-D` flag starts the daemon in debug mode. The `&` starts it as a - background process. You'll find these options useful when debugging code - development. You will need to hit `return` in order to get back to your shell prompt. - - > **Note**: The following command automates the `build`, - > `install`, and `run` steps above. Once the command below completes, hit `ctrl-z` to suspend the process, then run `bg 1` and hit `enter` to resume the daemon process in the background and get back to your shell prompt. - - ```none - hack/make.sh binary install-binary run - ``` - -9. Inside your container, check your Docker version. - - ```none - root@5f8630b873fe:/go/src/github.com/moby/moby# docker --version - Docker version 1.12.0-dev, build 6e728fb - ``` - - Inside the container you are running a development version. This is the version - on the current branch. It reflects the value of the `VERSION` file at the - root of your `docker-fork` repository. - -10. Run the `hello-world` image. - - ```none - root@5f8630b873fe:/go/src/github.com/moby/moby# docker run hello-world - ``` - -11. List the image you just downloaded. - - ```none - root@5f8630b873fe:/go/src/github.com/moby/moby# docker images - REPOSITORY TAG IMAGE ID CREATED SIZE - hello-world latest c54a2cc56cbb 3 months ago 1.85 kB - ``` - -12. Open another terminal on your local host. - -13. List the container running your development container. - - ```none - ubuntu@ubuntu1404:~$ docker ps - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - a8b2885ab900 docker-dev:dry-run-test "hack/dind bash" 43 minutes ago Up 43 minutes hungry_payne - ``` - - Notice that the tag on the container is marked with the `dry-run-test` branch name. - - -## Task 3. Make a code change - -At this point, you have experienced the "Docker inception" technique. That is, -you have: - -* forked and cloned the Docker Engine code repository -* created a feature branch for development -* created and started an Engine development container from your branch -* built a Docker binary inside of your Docker development container -* launched a `docker` daemon using your newly compiled binary -* called the `docker` client to run a `hello-world` container inside - your development container - -Running the `make BIND_DIR=. shell` command mounted your local Docker repository source into -your Docker container. - - > **Note**: Inspecting the `Dockerfile` shows a `COPY . /go/src/github.com/docker/docker` instruction, suggesting that dynamic code changes will _not_ be reflected in the container. However inspecting the `Makefile` shows that the current working directory _will_ be mounted via a `-v` volume mount. - -When you start to develop code though, you'll -want to iterate code changes and builds inside the container. If you have -followed this guide exactly, you have a BASH shell running a development -container. - -Try a simple code change and see it reflected in your container. For this -example, you'll edit the help for the `attach` subcommand. - -1. If you don't have one, open a terminal in your local host. - -2. Make sure you are in your `docker-fork` repository. - - ```none - $ pwd - /Users/mary/go/src/github.com/moxiegirl/docker-fork - ``` - - Your location should be different because, at least, your username is - different. - -3. Open the `cli/command/container/attach.go` file. - -4. Edit the command's help message. - - For example, you can edit this line: - - ```go - flags.BoolVar(&opts.noStdin, "no-stdin", false, "Do not attach STDIN") - ``` - - And change it to this: - - ```go - flags.BoolVar(&opts.noStdin, "no-stdin", false, "Do not attach STDIN (standard in)") - ``` - -5. Save and close the `cli/command/container/attach.go` file. - -6. Go to your running docker development container shell. - -7. Rebuild the binary by using the command `hack/make.sh binary` in the docker development container shell. - -8. Stop Docker if it is running. - -9. Copy the binaries to **/usr/bin** by entering the following commands in the docker development container shell (or use the `hack/make.sh binary install-binary run` command described above). - - ``` - cp bundles/1.12.0-dev/binary-client/docker* /usr/bin/ - cp bundles/1.12.0-dev/binary-daemon/docker* /usr/bin/ - ``` - -10. Start Docker. - -11. To view your change, run the `docker attach --help` command in the docker development container shell. - - ```bash - root@b0cb4f22715d:/go/src/github.com/moby/moby# docker attach --help - - Usage: docker attach [OPTIONS] CONTAINER - - Attach to a running container - - --detach-keys Override the key sequence for detaching a container - --help Print usage - --no-stdin Do not attach to STDIN (standard in) - --sig-proxy=true Proxy all received signals to the process - ``` - -You've just done the basic workflow for changing the Engine code base. You made -your code changes in your feature branch. Then, you updated the binary in your -development container and tried your change out. If you were making a bigger -change, you might repeat or iterate through this flow several times. - -## Where to go next - -Congratulations, you have successfully achieved Docker inception. You've had a -small experience of the development process. You've set up your development -environment and verified almost all the essential processes you need to -contribute. Of course, before you start contributing, [you'll need to learn one -more piece of the development process, the test framework](test-and-docs.md). diff --git a/opensource/project/set-up-git.md b/opensource/project/set-up-git.md deleted file mode 100644 index 88a3793e89..0000000000 --- a/opensource/project/set-up-git.md +++ /dev/null @@ -1,284 +0,0 @@ ---- -description: Describes how to set up your local machine and repository -keywords: GitHub account, repository, clone, fork, branch, upstream, Git, Go, make -title: Configure Git for contributing ---- - -Work through this page to configure Git and a repository you'll use throughout -the Contributor Guide. The work you do further in the guide, depends on the work -you do here. - -## Task 1. Fork and clone the Docker code - -Before contributing, you first fork the Docker code repository. A fork copies -a repository at a particular point in time. GitHub tracks for you where a fork -originates. - -As you make contributions, you change your fork's code. When you are ready, -you make a pull request back to the original Docker repository. If you aren't -familiar with this workflow, don't worry, this guide walks you through all the -steps. - -To fork and clone Docker: - -1. Open a browser and log into GitHub with your account. - -2. Go to the docker/docker repository. - -3. Click the "Fork" button in the upper right corner of the GitHub interface. - - ![Branch Signature](images/fork_docker.png) - - GitHub forks the repository to your GitHub account. The original - `docker/docker` repository becomes a new fork `YOUR_ACCOUNT/docker` under - your account. - -4. Copy your fork's clone URL from GitHub. - - GitHub allows you to use HTTPS or SSH protocols for clones. You can use the - `git` command line or clients like Subversion to clone a repository. - - ![Copy clone URL](images/copy_url.png) - - This guide assume you are using the HTTPS protocol and the `git` command - line. If you are comfortable with SSH and some other tool, feel free to use - that instead. You'll need to convert what you see in the guide to what is - appropriate to your tool. - -5. Open a terminal window on your local host and change to your home directory. - - ```bash - $ cd ~ - ``` - - In Windows, you'll work in your Docker Quickstart Terminal window instead of - Powershell or a `cmd` window. - -6. Create a `repos` directory. - - ```bash - $ mkdir repos - ``` - -7. Change into your `repos` directory. - - ```bash - $ cd repos - ``` - -8. Clone the fork to your local host into a repository called `docker-fork`. - - ```bash - $ git clone https://github.com/moxiegirl/docker.git docker-fork - ``` - - Naming your local repo `docker-fork` should help make these instructions - easier to follow; experienced coders don't typically change the name. - -9. Change directory into your new `docker-fork` directory. - - ```bash - $ cd docker-fork - ``` - - Take a moment to familiarize yourself with the repository's contents. List - the contents. - -## Task 2. Set your signature and an upstream remote - -When you contribute to Docker, you must certify you agree with the -Developer Certificate of Origin. -You indicate your agreement by signing your `git` commits like this: - -``` -Signed-off-by: Pat Smith -``` - -To create a signature, you configure your username and email address in Git. -You can set these globally or locally on just your `docker-fork` repository. -You must sign with your real name. You can sign your git commit automatically -with `git commit -s`. Docker does not accept anonymous contributions or contributions -through pseudonyms. - -As you change code in your fork, you'll want to keep it in sync with the changes -others make in the `docker/docker` repository. To make syncing easier, you'll -also add a _remote_ called `upstream` that points to `docker/docker`. A remote -is just another project version hosted on the internet or network. - -To configure your username, email, and add a remote: - -1. Change to the root of your `docker-fork` repository. - - ```bash - $ cd docker-fork - ``` - -2. Set your `user.name` for the repository. - - ```bash - $ git config --local user.name "FirstName LastName" - ``` - -3. Set your `user.email` for the repository. - - ```bash - $ git config --local user.email "emailname@mycompany.com" - ``` - -4. Set your local repo to track changes upstream, on the `docker` repository. - - ```bash - $ git remote add upstream https://github.com/moby/moby.git - ``` - -5. Check the result in your `git` configuration. - - ```bash - $ git config --local -l - core.repositoryformatversion=0 - core.filemode=true - core.bare=false - core.logallrefupdates=true - remote.origin.url=https://github.com/moxiegirl/docker.git - remote.origin.fetch=+refs/heads/*:refs/remotes/origin/* - branch.master.remote=origin - branch.master.merge=refs/heads/master - user.name=Mary Anthony - user.email=mary@docker.com - remote.upstream.url=https://github.com/moby/moby.git - remote.upstream.fetch=+refs/heads/*:refs/remotes/upstream/* - ``` - - To list just the remotes use: - - ```bash - $ git remote -v - origin https://github.com/moxiegirl/docker.git (fetch) - origin https://github.com/moxiegirl/docker.git (push) - upstream https://github.com/moby/moby.git (fetch) - upstream https://github.com/moby/moby.git (push) - ``` - -## Task 3. Create and push a branch - -As you change code in your fork, make your changes on a repository branch. -The branch name should reflect what you are working on. In this section, you -create a branch, make a change, and push it up to your fork. - -This branch is just for testing your config for this guide. The changes are part -of a dry run, so the branch name will be dry-run-test. To create and push -the branch to your fork on GitHub: - -1. Open a terminal and go to the root of your `docker-fork`. - - ```bash - $ cd docker-fork - ``` - -2. Create a `dry-run-test` branch. - - ```bash - $ git checkout -b dry-run-test - ``` - - This command creates the branch and switches the repository to it. - -3. Verify you are in your new branch. - - ```bash - $ git branch - * dry-run-test - master - ``` - - The current branch has an * (asterisk) marker. So, these results show you - are on the right branch. - -4. Create a `TEST.md` file in the repository's root. - - ```bash - $ touch TEST.md - ``` - -5. Edit the file and add your email and location. - - ![Add your information](images/contributor-edit.png) - - You can use any text editor you are comfortable with. - -6. Save and close the file. - -7. Check the status of your branch. - - ```bash - $ git status - On branch dry-run-test - Untracked files: - (use "git add ..." to include in what will be committed) - - TEST.md - - nothing added to commit but untracked files present (use "git add" to track) - ``` - - You've only changed the one file. It is untracked so far by git. - -8. Add your file. - - ```bash - $ git add TEST.md - ``` - - That is the only _staged_ file. Stage is fancy word for work that Git is - tracking. - -9. Sign and commit your change. - - ```bash - $ git commit -s -m "Making a dry run test." - [dry-run-test 6e728fb] Making a dry run test - 1 file changed, 1 insertion(+) - create mode 100644 TEST.md - ``` - - Commit messages should have a short summary sentence of no more than 50 - characters. Optionally, you can also include a more detailed explanation - after the summary. Separate the summary from any explanation with an empty - line. - -10. Push your changes to GitHub. - - ```bash - $ git push --set-upstream origin dry-run-test - Username for 'https://github.com': moxiegirl - Password for 'https://moxiegirl@github.com': - ``` - - Git prompts you for your GitHub username and password. Then, the command - returns a result. - - ```bash - Counting objects: 13, done. - Compressing objects: 100% (2/2), done. - Writing objects: 100% (3/3), 320 bytes | 0 bytes/s, done. - Total 3 (delta 1), reused 0 (delta 0) - To https://github.com/moxiegirl/docker.git - * [new branch] dry-run-test -> dry-run-test - Branch dry-run-test set up to track remote branch dry-run-test from origin. - ``` - -11. Open your browser to GitHub. - -12. Navigate to your Docker fork. - -13. Make sure the `dry-run-test` branch exists, that it has your commit, and the -commit is signed. - - ![Branch Signature](images/branch-sig.png) - -## Where to go next - -Congratulations, you have finished configuring both your local host environment -and Git for contributing. In the next section you'll [learn how to set up and -work in a Docker development container](set-up-dev-env.md). diff --git a/opensource/project/software-req-win.md b/opensource/project/software-req-win.md deleted file mode 100644 index 3c9422154a..0000000000 --- a/opensource/project/software-req-win.md +++ /dev/null @@ -1,181 +0,0 @@ ---- -description: How to set up a server to test Docker Engine on Windows -keywords: development, inception, container, image Dockerfile, dependencies, Go, artifacts, windows -title: Build and test Docker on Windows ---- - -This page explains how to get the software you need to build, test, and run the -Docker source code for Windows and setup the required software and services: - -- Windows containers -- GitHub account -- Git - -## Prerequisites - -### 1. Windows Server 2016 or Windows 10 with all Windows updates applied - -The major build number must be at least 14393. This can be confirmed, for example, -by running the following from an elevated PowerShell prompt - this sample output -is from a fully up to date machine as at mid-November 2016: - - - PS C:\> $(gin).WindowsBuildLabEx - 14393.447.amd64fre.rs1_release_inmarket.161102-0100 - -### 2. Git for Windows (or another git client) must be installed - -https://git-scm.com/download/win. - -### 3. The machine must be configured to run containers - -For example, by following the quick start guidance at -https://msdn.microsoft.com/en-us/virtualization/windowscontainers/quick_start/quick_start or https://github.com/docker/labs/blob/master/windows/windows-containers/Setup.md - -### 4. If building in a Hyper-V VM - -For Windows Server 2016 using Windows Server containers as the default option, -it is recommended you have at least 1GB of memory assigned; -For Windows 10 where Hyper-V Containers are employed, you should have at least -4GB of memory assigned. -Note also, to run Hyper-V containers in a VM, it is necessary to configure the VM -for nested virtualization. - -## Usage - -The following steps should be run from an elevated Windows PowerShell prompt. - ->**Note**: In a default installation of containers on Windows following the quick-start guidance at https://msdn.microsoft.com/en-us/virtualization/windowscontainers/quick_start/quick_start, -the `docker.exe` client must run elevated to be able to connect to the daemon). - -### 1. Docker Windows containers - -To test and run the Windows Docker daemon, you need a system that supports Windows Containers: - -- Windows 10 Anniversary Edition -- Windows Server 2016 running in a VM, on bare metal or in the cloud - -Check out the [getting started documentation](https://github.com/docker/labs/blob/master/windows/windows-containers/Setup.md) for details. - -### 2. GitHub account - -To contribute to the Docker project, you need a GitHub account. -A free account is fine. All the Docker project repositories are public and visible to everyone. - -This guide assumes that you have basic familiarity with Git and Github terminology -and usage. -Refer to [GitHub For Beginners: Don’t Get Scared, Get Started](http://readwrite.com/2013/09/30/understanding-github-a-journey-for-beginners-part-1/) -to get up to speed on Github. - -### 3. Git - -In PowerShell, run: - - Invoke-Webrequest "https://github.com/git-for-windows/git/releases/download/v2.7.2.windows.1/Git-2.7.2-64-bit.exe" -OutFile git.exe -UseBasicParsing - Start-Process git.exe -ArgumentList '/VERYSILENT /SUPPRESSMSGBOXES /CLOSEAPPLICATIONS /DIR=c:\git\' -Wait - setx /M PATH "$env:Path;c:\git\cmd" - -You are now ready clone and build the Docker source code. - -### 4. Clone Docker - -In a new (to pick up the path change) PowerShell prompt, run: - - git clone https://github.com/moby/moby - cd moby - -This clones the main Docker repository. Check out [Docker on GitHub](https://github.com/moby/moby) -to learn about the other software that powers the Docker platform. - -### 5. Build and run - -Create a builder-container with the Docker source code. You can change the source -code on your system and rebuild any time: - - docker build -t nativebuildimage -f .\Dockerfile.windows . - docker build -t nativebuildimage -f Dockerfile.windows -m 2GB . # (if using Hyper-V containers) - -To build Docker, run: - - $DOCKER_GITCOMMIT=(git rev-parse --short HEAD) - docker run --name binaries -e DOCKER_GITCOMMIT=$DOCKER_GITCOMMIT nativebuildimage hack\make.ps1 -Binary - docker run --name binaries -e DOCKER_GITCOMMIT=$DOCKER_GITCOMMIT -m 2GB nativebuildimage hack\make.ps1 -Binary # (if using Hyper-V containers) - -Copy out the resulting Windows Docker daemon binary to `dockerd.exe` in the -current directory: - - docker cp binaries:C:\go\src\github.com\docker\docker\bundles\docker.exe docker.exe - docker cp binaries:C:\go\src\github.com\docker\docker\bundles\dockerd.exe dockerd.exe - -To test it, stop the system Docker daemon and start the one you just built: - - Stop-Service Docker - .\dockerd.exe -D - -The other make targets work too, to run unit tests try: -`docker run --rm docker-builder sh -c 'cd /c/go/src/github.com/moby/moby; hack/make.sh test-unit'`. - -### 6. Remove the interim binaries container - -_(Optional)_ - - docker rm binaries - -### 7. Remove the image - -_(Optional)_ - -It may be useful to keep this image around if you need to build multiple times. -Then you can take advantage of the builder cache to have an image which has all -the components required to build the binaries already installed. - - docker rmi nativebuildimage - -## Validation - -The validation tests can only run directly on the host. -This is because they calculate information from the git repo, but the .git directory -is not passed into the image as it is excluded via `.dockerignore`. -Run the following from a Windows PowerShell prompt (elevation is not required): -(Note Go must be installed to run these tests) - - hack\make.ps1 -DCO -PkgImports -GoFormat - -## Unit tests - -To run unit tests, ensure you have created the nativebuildimage above. -Then run one of the following from an (elevated) Windows PowerShell prompt: - - docker run --rm nativebuildimage hack\make.ps1 -TestUnit - docker run --rm -m 2GB nativebuildimage hack\make.ps1 -TestUnit # (if using Hyper-V containers) - -To run unit tests and binary build, ensure you have created the nativebuildimage above. -Then run one of the following from an (elevated) Windows PowerShell prompt: - - docker run nativebuildimage hack\make.ps1 -All - docker run -m 2GB nativebuildimage hack\make.ps1 -All # (if using Hyper-V containers) - -## Windows limitations - -Don't attempt to use a bind mount to pass a local directory as the bundles -target directory. -It does not work (golang attempts for follow a mapped folder incorrectly). -Instead, use docker cp as per the example. - -`go.zip` is not removed from the image as it is used by the Windows CI servers -to ensure the host and image are running consistent versions of go. - -Nanoserver support is a work in progress. Although the image will build if the -`FROM` statement is updated, it will not work when running autogen through `hack\make.ps1`. -It is suspected that the required GCC utilities (eg gcc, windres, windmc) silently -quit due to the use of console hooks which are not available. - -The docker integration tests do not currently run in a container on Windows, -predominantly due to Windows not supporting privileged mode, so anything using a volume would fail. -They (along with the rest of the docker CI suite) can be run using -https://github.com/jhowardmsft/docker-w2wCIScripts/blob/master/runCI/Invoke-DockerCI.ps1. - -## Where to go next - -In the next section, you'll [learn how to set up and configure Git for -contributing to Docker](set-up-git.md). diff --git a/opensource/project/software-required.md b/opensource/project/software-required.md deleted file mode 100644 index 2cb39ae9a9..0000000000 --- a/opensource/project/software-required.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -description: Describes the software required to contribute to Docker -keywords: 'GitHub account, repository, Docker, Git, Go, make, ' -title: Get the required software for Linux or macOS ---- - -This page explains how to get the software you need to use a Linux or macOS -machine for Docker development. Before you begin contributing you must have: - -* a GitHub account -* `git` -* `make` -* `docker` - -You'll notice that `go`, the language that Docker is written in, is not listed. -That's because you don't need it installed; Docker's development environment -provides it for you. You'll learn more about the development environment later. - -## Task 1. Get a GitHub account - -To contribute to the Docker project, you will need a GitHub account. A free account is -fine. All the Docker project repositories are public and visible to everyone. - -You should also have some experience using both the GitHub application and `git` -on the command line. - -## Task 2. Install git - -Install `git` on your local system. You can check if `git` is on already on your -system and properly installed with the following command: - -```bash -$ git --version -``` - -This documentation is written using `git` version 2.2.2. Your version may be -different depending on your OS. - -## Task 3. Install make - -Install `make`. You can check if `make` is on your system with the following -command: - -```bash -$ make -v -``` - -This documentation is written using GNU Make 3.81. Your version may be different -depending on your OS. - -## Task 4. Install or upgrade Docker - -If you haven't already, install the Docker software using the -instructions for your operating system. -If you have an existing installation, check your version and make sure you have -the latest Docker. - -To check if `docker` is already installed on Linux: - -```bash -docker --version -Docker version 1.11.0, build 4dc5990 -``` - -On macOS or Windows, you should have installed Docker Toolbox which includes -Docker. You'll need to verify both Docker Machine and Docker. This -documentation was written on macOS using the following versions. - -```bash -$ docker-machine --version -docker-machine version 0.7.0, build a650a40 - -$ docker --version -Docker version 1.11.0, build 4dc5990 -``` - -## Tip for Linux users - -This guide assumes you have added your user to the `docker` group on your system. -To check, list the group's contents: - -``` -$ getent group docker -docker:x:999:ubuntu -``` - -If the command returns no matches, you have two choices. You can preface this -guide's `docker` commands with `sudo` as you work. Alternatively, you can add -your user to the `docker` group as follows: - -```bash -$ sudo usermod -aG docker ubuntu -``` - -You must log out and log back in for this modification to take effect. - - -## Where to go next - -In the next section, you'll [learn how to set up and configure Git for -contributing to Docker](set-up-git.md). \ No newline at end of file diff --git a/opensource/project/test-and-docs.md b/opensource/project/test-and-docs.md deleted file mode 100644 index 770c1ed55e..0000000000 --- a/opensource/project/test-and-docs.md +++ /dev/null @@ -1,364 +0,0 @@ ---- -description: Describes Docker's testing infrastructure -keywords: make test, make docs, Go tests, gofmt, contributing, running tests -title: Run tests and test documentation ---- - -Contributing includes testing your changes. If you change the Docker code, you -may need to add a new test or modify an existing one. Your contribution could -even be adding tests to Docker. For this reason, you need to know a little -about Docker's test infrastructure. - -Many contributors contribute documentation only. Or, a contributor makes a code -contribution that changes how Docker behaves and that change needs -documentation. For these reasons, you also need to know how to build, view, and -test the Docker documentation. - -This section describes tests you can run in the `dry-run-test` branch of your Docker -fork. If you have followed along in this guide, you already have this branch. -If you don't have this branch, you can create it or simply use another of your -branches. - -## Understand testing at Docker - -Docker tests use the Go language's test framework. In this framework, files -whose names end in `_test.go` contain test code; you'll find test files like -this throughout the Docker repo. Use these files for inspiration when writing -your own tests. For information on Go's test framework, see Go's testing package -documentation and the go test help. - -You are responsible for _unit testing_ your contribution when you add new or -change existing Docker code. A unit test is a piece of code that invokes a -single, small piece of code (_unit of work_) to verify the unit works as -expected. - -Depending on your contribution, you may need to add _integration tests_. These -are tests that combine two or more work units into one component. These work -units each have unit tests and then, together, integration tests that test the -interface between the components. The `integration` and `integration-cli` -directories in the Docker repository contain integration test code. - -Testing is its own specialty. If you aren't familiar with testing techniques, -there is a lot of information available to you on the Web. For now, you should -understand that, the Docker maintainers may ask you to write a new test or -change an existing one. - -## Run tests on your local host - -Before submitting a pull request with a code change, you should run the entire -Docker Engine test suite. The `Makefile` contains a target for the entire test -suite, named `test`. Also, it contains several targets for -testing: - -| Target | What this target does | -| ---------------------- | ---------------------------------------------- | -| `test` | Run the unit, integration, and docker-py tests | -| `test-unit` | Run just the unit tests | -| `test-integration-cli` | Run the integration tests for the CLI | -| `test-docker-py` | Run the tests for the Docker API client | - -Running the entire test suite on your current repository can take over half an -hour. To run the test suite, do the following: - -1. Open a terminal on your local host. - -2. Change to the root of your Docker repository. - - ```bash - $ cd docker-fork - ``` - -3. Make sure you are in your development branch. - - ```bash - $ git checkout dry-run-test - ``` - -4. Run the `make test` command. - - ```bash - $ make test - ``` - - This command does several things, it creates a container temporarily for - testing. Inside that container, the `make`: - - * creates a new binary - * cross-compiles all the binaries for the various operating systems - * runs all the tests in the system - - It can take approximate one hour to run all the tests. The time depends - on your host performance. The default timeout is 60 minutes, which is - defined in `hack/make.sh` (`${TIMEOUT:=60m}`). You can modify the timeout - value on the basis of your host performance. When they complete - successfully, you see the output concludes with something like this: - - ```none - Ran 68 tests in 79.135s - ``` - -## Run targets inside a development container - -If you are working inside a Docker development container, you use the -`hack/make.sh` script to run tests. The `hack/make.sh` script doesn't -have a single target that runs all the tests. Instead, you provide a single -command line with multiple targets that does the same thing. - -Try this now. - -1. Open a terminal and change to the `docker-fork` root. - -2. Start a Docker development image. - - If you are following along with this guide, you should have a - `dry-run-test` image. - - ```bash - $ docker run --privileged --rm -ti -v `pwd`:/go/src/github.com/moby/moby dry-run-test /bin/bash - ``` - -3. Run the tests using the `hack/make.sh` script. - - ```bash - root@5f8630b873fe:/go/src/github.com/moby/moby# hack/make.sh dynbinary binary cross test-unit test-integration-cli test-docker-py - ``` - - The tests run just as they did within your local host. - - Of course, you can also run a subset of these targets too. For example, to run - just the unit tests: - - ```bash - root@5f8630b873fe:/go/src/github.com/moby/moby# hack/make.sh dynbinary binary cross test-unit - ``` - - Most test targets require that you build these precursor targets first: - `dynbinary binary cross` - - -## Run unit tests - -We use golang standard [testing](https://golang.org/pkg/testing/) -package or [gocheck](https://labix.org/gocheck) for our unit tests. - -You can use the `TESTDIRS` environment variable to run unit tests for -a single package. - -```bash -$ TESTDIRS='opts' make test-unit -``` - -You can also use the `TESTFLAGS` environment variable to run a single test. The -flag's value is passed as arguments to the `go test` command. For example, from -your local host you can run the `TestBuild` test with this command: - -```bash -$ TESTFLAGS='-test.run ^TestValidateIPAddress$' make test-unit -``` - -On unit tests, it's better to use `TESTFLAGS` in combination with -`TESTDIRS` to make it quicker to run a specific test. - -```bash -$ TESTDIRS='opts' TESTFLAGS='-test.run ^TestValidateIPAddress$' make test-unit -``` - -## Run integration tests - -We use [gocheck](https://labix.org/gocheck) for our integration-cli tests. -You can use the `TESTFLAGS` environment variable to run a single test. The -flag's value is passed as arguments to the `go test` command. For example, from -your local host you can run the `TestBuild` test with this command: - -```bash -$ TESTFLAGS='-check.f DockerSuite.TestBuild*' make test-integration-cli -``` - -To run the same test inside your Docker development container, you do this: - -```bash -root@5f8630b873fe:/go/src/github.com/moby/moby# TESTFLAGS='-check.f TestBuild*' hack/make.sh binary test-integration-cli -``` - -## Test the Windows binary against a Linux daemon - -This explains how to test the Windows binary on a Windows machine set up as a -development environment. The tests will be run against a docker daemon -running on a remote Linux machine. You'll use **Git Bash** that came with the -Git for Windows installation. **Git Bash**, just as it sounds, allows you to -run a Bash terminal on Windows. - -1. If you don't have one open already, start a Git Bash terminal. - - ![Git Bash](images/git_bash.png) - -2. Change to the `docker` source directory. - - ```bash - $ cd /c/gopath/src/github.com/moby/moby - ``` - -3. Set `DOCKER_REMOTE_DAEMON` as follows: - - ```bash - $ export DOCKER_REMOTE_DAEMON=1 - ``` - -4. Set `DOCKER_TEST_HOST` to the `tcp://IP_ADDRESS:2376` value; substitute your - Linux machines actual IP address. For example: - - ```bash - $ export DOCKER_TEST_HOST=tcp://213.124.23.200:2376 - ``` - -5. Make the binary and run the tests: - - ```bash - $ hack/make.sh binary test-integration-cli - ``` - Some tests are skipped on Windows for various reasons. You can see which - tests were skipped by re-running the make and passing in the - `TESTFLAGS='-test.v'` value. For example - - ```bash - $ TESTFLAGS='-test.v' hack/make.sh binary test-integration-cli - ``` - - Should you wish to run a single test such as one with the name - 'TestExample', you can pass in `TESTFLAGS='-check.f TestExample'`. For - example - - ```bash - $ TESTFLAGS='-check.f TestExample' hack/make.sh binary test-integration-cli - ``` - -You can now choose to make changes to the Docker source or the tests. If you -make any changes, just run these commands again. - - -## Build and test the documentation - -The Docker documentation source files are in a centralized repository at -[https://github.com/docker/docker.github.io](https://github.com/docker/docker.github.io). The content is -written using extended Markdown, which you can edit in a plain text editor such as -Atom or Notepad. The docs are built using [Jekyll](https://jekyllrb.com/). - -Most documentation is developed in the centralized repository. The exceptions are -a project's API and CLI references and man pages, which are developed alongside -the project's code and periodically imported into the documentation repository. - -Always check your documentation for grammar and spelling. You can use -an online grammar checker such as [Hemingway Editor](http://www.hemingwayapp.com/) or a spelling or -grammar checker built into your text editor. If you spot spelling or grammar errors, -fixing them is one of the easiest ways to get started contributing to opensource -projects. - -When you change a documentation source file, you should test your change -locally to make sure your content is there and any links work correctly. You -can build the documentation from the local host. - -### Build the docs for docs.docker.com - -You can build the docs using a Docker container or by using Jekyll directly. -Using the Docker container requires no set-up but is slower. Using Jekyll -directly requires you to install some prerequisites, but is faster on each build. - -#### Use Docker Compose - -The easiest way to build the docs locally on macOS, Windows, or Linux is to use -`docker-compose`. If you have not yet installed `docker-compose`, -[follow these installation instructions](/compose/install/). - -In the root of the repository, issue the following command: - -```bash -$ docker-compose up -``` - -This command will create and start service `docs` defined in `docker-compose.yml`, -which will build an image named `docs/docstage` and launch a container with Jekyll and all its dependencies configured -correctly. The container uses Jekyll to incrementally build and serve the site using the -files in the local repository. - -Go to `http://localhost:4000/` in your web browser to view the documentation. - -The container runs in the foreground. It will continue to run and incrementally build the site when changes are -detected, even if you change branches. - -To stop the container, use `CTRL+C`. - -To start the container again, use the following command: - -```bash -$ docker-compose start docs -``` - -#### Use Jekyll directly - -If for some reason you are unable to use Docker Compose, you can use Jekyll directly. - -**Prerequisites:** - -- You need a recent version of Ruby installed. If you are on macOS, install Ruby - and Bundle using homebrew. - - ```bash - brew install ruby - brew install bundle - ``` - -- Use `bundle` to install Jekyll and its dependencies from the bundle in the - centralized documentation repository. Within your clone of the - [https://github.com/docker/docker.github.io](https://github.com/docker/docker.github.io) - repository, issue the following command: - - ```bash - bundle install - ``` - -**To build the website locally:** - - 1. Issue the `jekyll serve` command. This will build - the static website and serve it in a small web server on port 4000. If it - fails, examine and fix the errors and run the command again. - - 2. You can keep making changes to the Markdown files in another terminal - window, and Jekyll will detect the changes and rebuild the relevant HTML - pages automatically. - - 3. To stop the web server, issue `CTRL+C`. - -To serve the website using Github Pages on your fork, first -[enable Github Pages in your fork](https://pages.github.com/) or rename your fork -to `.github.io`, then push your -feature branch to your fork's Github Pages branch, which is `gh-pages` or `master`, -depending on whether you manually enabled Github Pages or renamed your fork. -Within a few minutes, the site will be available on your Github Pages URL. - -Review your documentation changes on the local or Github Pages site. When you -are satisfied with your changes, submit your pull request. - - -### Review the reference docs for your project - -Some projects, such as Docker Engine, maintain reference documents, such as man -pages, CLI command references, and API endpoint references. These files are -maintained within each project and periodically imported into the centralized -documentation repository. If you change the behavior of a command or endpoint, -including changing the help text, be sure that the associated reference -documentation is updated as part of your pull request. - -These reference documents are usually under the `docs/reference/` directory or -the `man/` directory. The best way to review them is to push the changes to -your fork and view the Markdown files in Github. The style will not match with -docs.docker.com, but you will be able to preview the changes. - - -## Where to go next - -Congratulations, you have successfully completed the basics you need to -understand the Docker test framework. In the next steps, you use what you have -learned so far to [contribute to Docker by working on an -issue](../workflow/make-a-contribution.md). diff --git a/opensource/project/who-written-for.md b/opensource/project/who-written-for.md deleted file mode 100644 index 2237792f5e..0000000000 --- a/opensource/project/who-written-for.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -description: Introduction to project contribution at Docker -keywords: Gordon, introduction, turtle, machine, libcontainer, how to -redirect_from: -- /project/who-written-for/ -title: README first ---- - -This section of the documentation contains a guide for Docker users who want to -contribute code or documentation to the Docker Engine project. As a community, we -share rules of behavior and interaction. Make sure you are familiar with the community guidelines before continuing. - -## Where and what you can contribute - -The Docker project consists of not just one but several repositories on GitHub. -So, in addition to the `docker/docker` repository, there is the -`docker/compose` repo, the `docker/machine` repo, and several more. -Contribute to any of these and you contribute to the Docker project. - -Not all Docker repositories use the Go language. Also, each repository has its -own focus area. So, if you are an experienced contributor, think about -contributing to a Docker repository that has a language or a focus area you are -familiar with. - -If you are new to the open source community, to Docker, or to formal -programming, you should start out contributing to the `docker/docker` -repository. Why? Because this guide is written for that repository specifically. - -Finally, code or documentation isn't the only way to contribute. You can report -an issue, add to discussions in our community channel, write a blog post, or -take a usability test. You can even propose your own type of contribution. -Right now we don't have a lot written about this yet, so just email - if this type of contributing interests you. - -## A turtle is involved - -![Gordon](../images/gordon.jpeg) - -Enough said. - -## How to use this guide - -This is written for the distracted, the overworked, the sloppy reader with fair -`git` skills and a failing memory for the GitHub GUI. The guide attempts to -explain how to use the Docker Engine development environment as precisely, -predictably, and procedurally as possible. - -Users who are new to Engine development should start by setting up their -environment. Then, they should try a simple code change. After that, you should -find something to work on or propose a totally new change. - -If you are a programming prodigy, you still may find this documentation useful. -Please feel free to skim past information you find obvious or boring. - -## How to get started - -Start by getting the software you require. If you are on Mac or Linux, go to -[get the required software for Linux or macOS](software-required.md). If you are -on Windows, see [get the required software for Windows](software-req-win.md). diff --git a/opensource/ways/community.md b/opensource/ways/community.md deleted file mode 100644 index 9badba3159..0000000000 --- a/opensource/ways/community.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -description: Support the community -keywords: support, community, users, irc -title: Support the community ---- - -With millions of Docker users all over the world, there's always someone who -needs a helping hand. Like many open source projects, the Docker project relies -on community support channels like forums, IRC, and StackOverflow. You should -contribute mentoring if you have good knowledge of: - -* how open source projects run -* using Docker in some particular domain (for example, testing or deployment) -* using Git, Go, GitHub, IRC, or other common tools - -Also, choose mentoring if you like to be happy. Studies show that helping others is a great way to -boost your own well being. - - -## Docker users - -Docker users are people using Docker in their daily work. To help Docker users, visit: - -* the Docker Community Forum -* the `#docker` channel on Freenode IRC -* StackOverflow - -You can also check the list of -open user questions on the Docker project. - - -## Docker contributors - -Docker contributors are people like you contributing to Docker open source. -Contributors may need help with IRC, Go programming, Markdown, or with other -aspects of contributing. To help Docker contributors, visit: - -* the Docker Gitter IM - room -* the docker-dev Google group -* the `#docker-dev` channel on Freenode IRC diff --git a/opensource/ways/index.md b/opensource/ways/index.md deleted file mode 100644 index 5faf1fe47e..0000000000 --- a/opensource/ways/index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -description: Contribute code -keywords: governance, board, members, profiles -title: Other ways to contribute ---- - -* [Support the community](community.md) -* [Organize our Issues](issues.md) -* [Organize a Docker Meetup](meetups.md) -* [Test contributions](test.md) \ No newline at end of file diff --git a/opensource/ways/issues.md b/opensource/ways/issues.md deleted file mode 100644 index 83b9a2b0af..0000000000 --- a/opensource/ways/issues.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -description: Organize our issues -keywords: governance, board, members, profiles -title: Organize our issues ---- - -The Docker projects use GitHub issues to record issues and feature requests that -come in from contributors. Help us organize our work by triaging. Triage is the -process of reviewing incoming issue tickets, gathering more information about -the issue, and verifying whether or not the issue is valid. - -You should triage if you want to discover which Docker features other contributors -think are important. Triage is a great choice if you have an interest -or experience in software product management or project management. - - -## What kind of issues can I triage? - -Docker users and contributors create new issues if they want to: - -* report a problem they had with Docker software -* request a new feature -* ask a question - -## How do I triage? - -Follow these steps: - -1. Sign up for a [Github account](https://github.com). - -2. Visit a Docker repository and press the **Watch** button. - - This tells GitHub to notify you of new issues. Depending on your settings, - notification go to your GitHub or email inbox. Some of repositories you can watch are: - - | Repository | Description | - |---------- |-------------| - | [moby/moby](https://github.com/moby/moby) | Moby is the open-source application container engine, not including the API or CLI. | - | [docker/cli](https://github.com/docker/cli) | Docker API and CLI source code and documentation generation scripts. | - | [docker/machine](https://github.com/docker/machine) | Software for the easy and quick creation of Docker hosts on your computer, on cloud providers, and inside your own data center. | - | [kitematic/kitematic](https://github.com/kitematic/kitematic) | Kitematic is a simple application for managing Docker containers on macOS and Windows. | - | [docker/swarmkit](https://github.com/docker/swarmkit) | Orchestration for Docker. Deploy services and stacks (declarative definitions of groups of containers) to a cluster of Docker hosts. | - | [docker/compose](https://github.com/docker/compose) | Define and run complex applications using one or many interlinked containers. | - - See [the complete list of Docker repositories](https://github.com/docker) on GitHub. - -3. Choose an issue from the [list of untriaged issues](https://github.com/moby/moby/issues?q=is%3Aopen+is%3Aissue+-label%3Akind%2Fproposal+-label%3Akind%2Fenhancement+-label%3Akind%2Fbug+-label%3Akind%2Fcleanup+-label%3Akind%2Fgraphics+-label%3Akind%2Fwriting+-label%3Akind%2Fsecurity+-label%3Akind%2Fquestion+-label%3Akind%2Fimprovement+-label%3Akind%2Ffeature). - -4. Follow [the triage process](https://github.com/moby/moby/blob/master/project/ISSUE-TRIAGE.md) to triage the issue. - - The triage process asks you to add both a `kind/` and a `exp/` label to each - issue. Because you are not a Docker maintainer, you add these through comments. - Simply add a `+label` keyword to an issue comment: - - ![Example](../images/triage-label.png) - - For example, the `+exp/beginner` and `+kind/writing` labels would triage an issue as - beginner writing task. For descriptions of valid labels, see [the triage process](https://github.com/moby/moby/blob/master/project/ISSUE-TRIAGE.md). - -5. Triage another issue. diff --git a/opensource/ways/meetups.md b/opensource/ways/meetups.md deleted file mode 100644 index 74e677c617..0000000000 --- a/opensource/ways/meetups.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -description: Organize a Docker Meetup -keywords: Docker, meetup, hosting, organizing -title: Organize a Docker meetup ---- - -Anyone interested in Docker can become an active member of the Docker community -by becoming a co-organizer of a Docker Meetup group. - -If a Meetup group does not already exist in your area and you are willing to -start a new one, the best way to proceed is to contact us so that we can create -it for you. We will always agree to create a new Docker Meetup group as long as -it makes sense geographically speaking. - -If you have already created a Docker Meetup group that is fine, we will simply -ask you to add us as a co-organizer so that we can ensure a consistent support -to the group in terms of community and Meetup management. - -Before contacting us to create a new Docker Meetup Group, take a look at our -Meetup Groups page to make sure a group does not already exist in the area. - -## Get started putting on a Docker Meetup - -Now that you are a co-organizer of a Docker Meetup Group, here are a few tips and -suggestions to help you get started: - -* Attend similar DevOps or Developers Meetups to gain experience and gauge interest in Docker -* Contact other people interested in Docker to help you organize and promote future Meetups -* Research High-Tech companies in your area willing to host a Docker Meetup event -* Research what would be the best date(s) to schedule the Meetups based on availabilities with regard to competing events in the area and other calendar imperative -* Research what are the topic of interest to your audience prior to set an agenda for the meetup -* Pay attention to the Meetup page aesthetics, add logos and pictures, invite members to leave comments and reply to these comments -* Promote the event on social media and make sure that the list of keywords is well define if you have created the Docker Meetup Group on your own - -## How Docker can help you organize - -We can support the co-organizers of the Docker Meetup Groups based on their specific needs. For instance, we might / will be able to: - -* Send you Docker T-shirts and stickers -* Put you in contact with other people interested in being a co-organizer of a Docker Meetup group, and which are in the same area -* Put you in contact with companies willing to host a Docker Meetup in your area -* Introduce you to people willing to give a lightning talk about Docker -* Promote your Docker Group on Docker.com, Docker Weekly and Social Media - Hackday Picture - -## Host a Docker meetup at your location - -![Meetup](../images/docker-friends.png) - -## Want to host a Docker Meetup? - -We are always looking for new office space to host Docker Meetups. If your -company is willing to host a Docker Meetup, please contact us by email at -meetup@docker.com. Previous Docker Meetups have been hosted by companies such -as Rackspace, Twitter, MongoDB, BrightCove, DigitalOcean, Viadeo and Edmodo. -### How many attendees? - -The company hosting the event fixes the number of attendees depending on their -office size and availability. This number usually varies between 30 and 200. - -### How long is a Docker Meetup? - -Once again, each company hosting the event decides when does the meetup start, -and how long it lasts. Usual meetups tend to last 2 hours, and start between -4pm and 6pm. diff --git a/opensource/ways/test.md b/opensource/ways/test.md deleted file mode 100644 index 5f0276ad64..0000000000 --- a/opensource/ways/test.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -description: Testing contributions -keywords: test, source, contributions, Docker -title: Testing contributions ---- - -Testing is about software quality, performance, reliability, or product -usability. We develop and test Docker software before we release but we are -human. So, we make mistakes, we get forgetful, or we just don't have enough -time to do everything. - -Choose to contribute testing if you want to improve Docker software and -processes. Testing is a good choice for contributors that have experience -in software testing, usability testing, or who are otherwise great at spotting -problems. - -## What can you contribute to testing? - -* Write a blog about how your company uses Docker as its test infrastructure. -* Take an online usability test or create a usability test about Docker. -* Test one of Docker's official images. -* Test the Docker documentation. - - -## Test the Docker documentation - -Testing documentation is relatively easy: - -1. Find a page in [Docker's documentation](/) that contains a procedure or example you want to test. - - You should choose something that _should work_ on your machine. For example, - [creating a base image](/engine/userguide/eng-image/baseimages/){: target="_blank" class="_" } - is something anyone with Docker can do, while [changing volume directories in Kitematic](https://kitematic.com/docs/managing-volumes/){: target="_blank" class="_" } - requires Kitematic installed on a Mac. - -2. Try and follow the procedure or recreate the example. - - Look for: - - * Are the steps clearly laid out and identifiable? - * Are the steps in the right order? - * Did you get the results the procedure or example said you would? - -3. If you couldn't complete the procedure or example, - [file an issue](https://github.com/moby/moby/issues/new){: target="_blank" class="_" }{: target="_blank" class="_" }. - -## Test code in Docker - -If you are interested in writing or fixing test code for the Docker project, learn about our test infrastructure. - -View our open test issues in Docker for something to work on. Or, create one of your own. diff --git a/opensource/workflow/advanced-contributing.md b/opensource/workflow/advanced-contributing.md deleted file mode 100644 index 7a87c26512..0000000000 --- a/opensource/workflow/advanced-contributing.md +++ /dev/null @@ -1,152 +0,0 @@ ---- -description: Explains workflows for refactor and design proposals -keywords: contribute, project, design, refactor, proposal -title: Advanced contributing ---- - -In this section, you learn about the more advanced contributions you can make. -They are advanced because they have a more involved workflow or require greater -programming experience. Don't be scared off though, if you like to stretch and -challenge yourself, this is the place for you. - -This section gives generalized instructions for advanced contributions. You'll -read about the workflow but there are not specific descriptions of commands. -Your goal should be to understand the processes described. - -At this point, you should have read and worked through the earlier parts of -the project contributor guide. You should also have -[made at least one project contribution](make-a-contribution/){: target="_blank" class="_"}. - -## Refactor or cleanup proposal - -A refactor or cleanup proposal changes Docker's internal structure without -altering the external behavior. To make this type of proposal: - -1. Fork `docker/docker`. - -2. Make your changes in a feature branch. - -3. Sync and rebase with `master` as you work. - -3. Run the full test suite. - -4. Submit your code through a pull request (PR). - - The PR's title should have the format: - - **Cleanup:** _short title_ - - If your changes required logic changes, note that in your request. - -5. Work through Docker's review process until merge. - - -## Design proposal - -A design proposal solves a problem or adds a feature to the Docker software. -The process for submitting design proposals requires two pull requests, one -for the design and one for the implementation. - -![Simple process](images/proposal.png) - -The important thing to notice is that both the design pull request and the -implementation pull request go through a review. In other words, there is -considerable time commitment in a design proposal; so, you might want to pair -with someone on design work. - -The following provides greater detail on the process: - -1. Come up with an idea. - - Ideas usually come from limitations users feel working with a product. So, - take some time to really use Docker. Try it on different platforms; explore - how it works with different web applications. Go to some community events - and find out what other users want. - -2. Review existing issues and proposals to make sure no other user is proposing a similar idea. - - The design proposals are - [all online in our GitHub pull requests](https://github.com/docker/docker.github.io/pulls). - -3. Talk to the community about your idea. - - We have lots of [community forums](https://forums.docker.com){: target="_blank" class="_"} - where you can get feedback on your idea. Float your idea in a forum or two - to get some commentary going on it. - -4. Fork `docker/docker` and clone the repo to your local host. - -5. Create a new Markdown file in the area you wish to change. - - For example, if you want to redesign our daemon, create a new file under the - `daemon/` folder. - -6. Name the file descriptively, for example `redesign-daemon-proposal.md`. - -7. Write a proposal for your change into the file. - - This is a Markdown file that describes your idea. Your proposal - should include information like: - - * Why is this change needed or what are the use cases? - * What are the requirements this change should meet? - * What are some ways to design/implement this feature? - * Which design/implementation do you think is best and why? - * What are the risks or limitations of your proposal? - - This is your chance to convince people your idea is sound. - -8. Submit your proposal in a pull request to `docker/docker`. - - The title should have the format: - - **Proposal:** _short title_ - - The body of the pull request should include a brief summary of your change - and then say something like "_See the file for a complete description_". - -9. Refine your proposal through review. - - The maintainers and the community review your proposal. You'll need to - answer questions and sometimes explain or defend your approach. This is - chance for everyone to both teach and learn. - -10. Pull request accepted. - - Your request may also be rejected. Not every idea is a good fit for Docker. - Let's assume though your proposal succeeded. - -11. Implement your idea. - - Implementation uses all the standard practices of any contribution. - - * fork `docker/docker` - * create a feature branch - * sync frequently back to master - * test as you go and full test before a PR - - If you run into issues, the community is there to help. - -12. When you have a complete implementation, submit a pull request back to `docker/docker`. - -13. Review and iterate on your code. - - If you are making a large code change, you can expect greater scrutiny - during this phase. - -14. Acceptance and merge! - -## About the advanced process - -Docker is a large project. Our core team gets a great many design proposals. -Design proposal discussions can span days, weeks, and longer. The number of comments can reach the 100s. -In that situation, following the discussion flow and the decisions reached is crucial. - -Making a pull request with a design proposal simplifies this process: - -* you can leave comments on specific design proposal line -* replies around line are easy to track -* as a proposal changes and is updated, pages reset as line items resolve -* GitHub maintains the entire history - -While proposals in pull requests do not end up merged into a master repository, they provide a convenient tool for managing the design process. diff --git a/opensource/workflow/coding-style.md b/opensource/workflow/coding-style.md deleted file mode 100644 index 207e0053d7..0000000000 --- a/opensource/workflow/coding-style.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -description: List of guidelines for coding Docker contributions -keywords: change, commit, squash, request, pull request, test, unit test, integration tests, Go, gofmt, LGTM -title: Coding style checklist ---- - -This checklist summarizes the material you experienced working through [make a -code contribution](make-a-contribution.md) and [advanced -contributing](advanced-contributing.md). The checklist applies to both -program code and documentation code. - -## Change and commit code - -* Fork the `docker/docker` repository. - -* Make changes on your fork in a feature branch. Name your branch `XXXX-something` - where `XXXX` is the issue number you are working on. - -* Run `gofmt -s -w file.go` on each changed file before - committing your changes. Most editors have plug-ins that do this automatically. - -* Run `golint` on each changed file before - committing your changes. - -* Update the documentation when creating or modifying features. - -* Commits that fix or close an issue should reference it in the commit message - `Closes #XXXX` or `Fixes #XXXX`. Mentions help by automatically closing the - issue on a merge. - -* After every commit, run the test suite and ensure it is passing. - -* Sync and rebase frequently as you code to keep up with `docker` master. - -* Set your `git` signature and make sure you sign each commit. - -* Do not add yourself to the `AUTHORS` file. This file is autogenerated from the - Git history. - -## Tests and testing - -* Submit unit tests for your changes. - -* Make use of the builtin Go test framework built. - -* Use existing Docker test files (`name_test.go`) for inspiration. - -* Run [the full test suite](../project/test-and-docs.md) on your - branch before submitting a pull request. - -* Run `make docs` to build the documentation and then check it locally. - -* Use an online grammar - checker or similar to test you documentation changes for clarity, - concision, and correctness. - -## Pull requests - -* Sync and cleanly rebase on top of Docker's `master` without multiple branches - mixed into the PR. - -* Before the pull request, squash your commits into logical units of work using - `git rebase -i` and `git push -f`. - -* Include documentation changes in the same commit so that a revert would - remove all traces of the feature or fix. - -* Reference each issue in your pull request description (`#XXXX`). - -## Respond to pull requests reviews - -* Docker maintainers use LGTM (**l**ooks-**g**ood-**t**o-**m**e) in PR comments - to indicate acceptance. - -* Code review comments may be added to your pull request. Discuss, then make - the suggested modifications and push additional commits to your feature - branch. - -* Incorporate changes on your feature branch and push to your fork. This - automatically updates your open pull request. - -* Post a comment after pushing to alert reviewers to PR changes; pushing a - change does not send notifications. - -* A change requires LGTMs from an absolute majority maintainers of an - affected component. For example, if you change `docs/` and `registry/` code, - an absolute majority of the `docs/` and the `registry/` maintainers must - approve your PR. - -## Merges after pull requests - -* After a merge, [a master build](https://master.dockerproject.org/) is - available almost immediately. diff --git a/opensource/workflow/create-pr.md b/opensource/workflow/create-pr.md deleted file mode 100644 index 725f1c70db..0000000000 --- a/opensource/workflow/create-pr.md +++ /dev/null @@ -1,127 +0,0 @@ ---- -description: Basic workflow for Docker contributions -keywords: contribute, pull request, review, workflow, beginner, squash, commit -title: Create a pull request (PR) ---- - -A pull request (PR) sends your changes to the Docker maintainers for review. You -create a pull request on GitHub. A pull request "pulls" changes from your forked -repository into the `docker/docker` repository. - -You can see the -list of active pull requests to Docker on GitHub. - -## Check your work - -Before you create a pull request, check your work. - -1. In a terminal window, go to the root of your `docker-fork` repository. - - $ cd ~/repos/docker-fork - -2. Checkout your feature branch. - - $ git checkout 11038-fix-rhel-link - Switched to branch '11038-fix-rhel-link' - -3. Run the full test suite on your branch. - - $ make test - - All the tests should pass. If they don't, find out why and correct the - situation. - -4. Commit and push any changes that result from your checks. - -## Rebase your branch - -Always rebase and squash your commits before making a pull request. - -1. Checkout your feature branch in your local `docker-fork` repository. - - This is the branch associated with your request. - -2. Fetch any last minute changes from `docker/docker`. - - $ git fetch upstream master - From github.com:docker/docker - * branch master -> FETCH_HEAD - -3. Start an interactive rebase. - - $ git rebase -i upstream/master - -4. Rebase opens an editor with a list of commits. - - pick 1a79f55 Tweak some of the other text for grammar - pick 53e4983 Fix a link - pick 3ce07bb Add a new line about RHEL - -5. Replace the `pick` keyword with `squash` on all but the first commit. - - pick 1a79f55 Tweak some of the other text for grammar - squash 53e4983 Fix a link - squash 3ce07bb Add a new line about RHEL - - After you save the changes and quit from the editor, git starts - the rebase, reporting the progress along the way. Sometimes - your changes can conflict with the work of others. If git - encounters a conflict, it stops the rebase, and prints guidance - for how to correct the conflict. - -6. Edit and save your commit message. - - $ git commit -s - - Make sure your message includes your signature. - -7. Force push any changes to your fork on GitHub. - - $ git push -f origin 11038-fix-rhel-link - -## Create a PR on GitHub - -You create and manage PRs on GitHub: - -1. Open your browser to your fork on GitHub. - - You should see the latest activity from your branch. - - ![Latest commits](images/latest_commits.png) - - -2. Click "Compare & pull request." - - The system displays the pull request dialog. - - ![PR dialog](images/to_from_pr.png) - - The pull request compares your changes to the `master` branch on the - `docker/docker` repository. - -3. Edit the dialog's description and add a reference to the issue you are fixing. - - GitHub helps you out by searching for the issue as you type. - - ![Fixes issue](images/fixes_num.png) - -4. Scroll down and verify the PR contains the commits and changes you expect. - - For example, is the file count correct? Are the changes in the files what - you expect? - - ![Commits](images/commits_expected.png) - -5. Press "Create pull request". - - The system creates the request and opens it for you in the `docker/docker` - repository. - - ![Pull request made](images/pull_request_made.png) - - -## Where to go next - -Congratulations, you've created your first pull request to Docker. The next -step is for you learn how to [participate in your PR's -review](review-pr.md). diff --git a/opensource/workflow/find-an-issue.md b/opensource/workflow/find-an-issue.md deleted file mode 100644 index 01773f2715..0000000000 --- a/opensource/workflow/find-an-issue.md +++ /dev/null @@ -1,286 +0,0 @@ ---- -description: Basic workflow for Docker contributions -keywords: contribute, issue, review, workflow, beginner, expert, squash, commit -title: Find and claim an issue ---- - - - - -As a contributor, you can work on any open issue you want. You can view -issues in the **Issues** tab in every repository. If you are new to -contributing, use the filter option to find suitable issues. You can -filter issues by Author, Labels, Milestones, and Assignee or sort by -time such as newest and oldest. - -## Understand the issue types -To help you identify the different types of issues, our maintainers -assign labels to issues. Labels are color-coded and help you categorize -and filter issues. There are four labels categories: kind, area, -experience, and priority. You can filter using one or more labels. The -kind and experience labels are useful for new contributors. - -The following table describes the kind labels. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Kind LabelDescription
kind/bug - These issues contain bugs. The cause may or may not be known - at triage time so debugging should be taken account into the - time estimate. -
kind/docs - These issues contain documentation, man pages, articles, - blogs, or other significant word-driven task. -
kind/enhancement - These issues contain enhancements that are not bugs or new - features but can improve usability or performance of - a project component. -
kind/feature - These issues contain new features, functionality, and - elements that the project does not currently support. -
kind/question - These issues contain a user or contributor question that - requires a response. -
- - -The following table describes the experience level guidelines. - - - - - - - - - - - - - - - - - - - - - - -
Exp LabelDescription
exp/beginner - You are new to Docker and Golang and want to start - contributing to the project. These issues are for beginners who - want to learn the basics. We encourage new contributors to start - with exp/beginner issues. -
exp/intermediate - You understand the core concepts of Docker and are - comfortable with Golang. These issues are for intermediates who - want to dive deeper into the project. -
exp/expert - You are proficient with Docker and Golang and are actively - involved in the community. These issues are for experts who - understand the rationale behind design decisions and where the - project is headed. -
- -As stated, these labels are guidelines. You might have written a whole -plugin for Docker in a personal project and never contributed to -Docker. With that kind of experience, you could take on an exp/expert issue. - -## Claim a beginner issue - -To claim an issue: - -1. Go to the `docker/docker` repository. - -2. Click the **Issues** tab. - - A list of the open issues appears. - - ![Open issues](images/issue_list.png) - -3. From the **Labels** drop-down, select exp/beginner. - - The system filters to show only open exp/beginner issues. - -4. Open an issue that interests you. - - The comments on the issues describe the problem and can provide information for a potential - solution. - -5. When you find an open issue that both interests you and is unclaimed, add a -`#dibs` comment. Make sure that no other user has chosen to work on the issue. - - The project does not permit external contributors to assign issues to themselves. Read - the comments to find if a user claimed the issue by leaving a - `#dibs` comment on the issue. - -7. Your issue # will be different depending on what you claimed. After a moment, Gordon the Docker -bot, changes the issue status to claimed. The following example shows issue #11038. - - ![Easy issue](images/easy_issue.png) - -8. Make a note of the issue number; you will need it for later. - -## Sync your fork and create a new branch - -If you have followed along in this guide, you forked the `docker/docker` -repository. Maybe that was an hour ago or a few days ago. In any case, before -you start working on your issue, sync your repository with the upstream -`docker/docker` master. Syncing ensures your repository has the latest -changes. - -To sync your repository: - -1. Open a terminal on your local host. - -2. Change directory to the `docker-fork` root. - - $ cd ~/repos/docker-fork - -3. Checkout the master branch. - - $ git checkout master - Switched to branch 'master' - Your branch is up-to-date with 'origin/master'. - - Recall that `origin/master` is a branch on your remote GitHub repository. - -4. Make sure you have the upstream remote `docker/docker` by listing them. - - $ git remote -v - origin https://github.com/moxiegirl/docker.git (fetch) - origin https://github.com/moxiegirl/docker.git (push) - upstream https://github.com/moby/moby.git (fetch) - upstream https://github.com/moby/moby.git (push) - - If the `upstream` is missing, add it. - - $ git remote add upstream https://github.com/moby/moby.git - -5. Fetch all the changes from the `upstream master` branch. - - $ git fetch upstream master - remote: Counting objects: 141, done. - remote: Compressing objects: 100% (29/29), done. - remote: Total 141 (delta 52), reused 46 (delta 46), pack-reused 66 - Receiving objects: 100% (141/141), 112.43 KiB | 0 bytes/s, done. - Resolving deltas: 100% (79/79), done. - From github.com:docker/docker - * branch master -> FETCH_HEAD - -7. Rebase your local master with the `upstream/master`. - - $ git rebase upstream/master - First, rewinding head to replay your work on top of it... - Fast-forwarded master to upstream/master. - - This command applies all the commits from the upstream master to your local - master. - -8. Check the status of your local branch. - - $ git status - On branch master - Your branch is ahead of 'origin/master' by 38 commits. - (use "git push" to publish your local commits) - nothing to commit, working directory clean - - Your local repository now has all the changes from the `upstream` remote. You - need to push the changes to your own remote fork which is `origin master`. - -9. Push the rebased master to `origin master`. - - $ git push origin master - Username for 'https://github.com': moxiegirl - Password for 'https://moxiegirl@github.com': - Counting objects: 223, done. - Compressing objects: 100% (38/38), done. - Writing objects: 100% (69/69), 8.76 KiB | 0 bytes/s, done. - Total 69 (delta 53), reused 47 (delta 31) - To https://github.com/moxiegirl/docker.git - 8e107a9..5035fa1 master -> master - -9. Create a new feature branch to work on your issue. - - Your branch name should have the format `XXXX-descriptive` where `XXXX` is - the issue number you are working on. For example: - - $ git checkout -b 11038-fix-rhel-link - Switched to a new branch '11038-fix-rhel-link' - - Your branch should be up-to-date with the `upstream/master`. Why? Because you - branched off a freshly synced master. Let's check this anyway in the next - step. - -9. Rebase your branch from `upstream/master`. - - $ git rebase upstream/master - Current branch 11038-fix-rhel-link is up to date. - - At this point, your local branch, your remote repository, and the Docker - repository all have identical code. You are ready to make changes for your - issue. - - -## Where to go next - -At this point, you know what you want to work on and you have a branch to do -your work in. Go onto the next section to learn [how to work on your -changes](work-issue.md). diff --git a/opensource/workflow/images/commits_expected.png b/opensource/workflow/images/commits_expected.png deleted file mode 100644 index 2ffe18a790..0000000000 Binary files a/opensource/workflow/images/commits_expected.png and /dev/null differ diff --git a/opensource/workflow/images/easy_issue.png b/opensource/workflow/images/easy_issue.png deleted file mode 100644 index ef6ce0bc42..0000000000 Binary files a/opensource/workflow/images/easy_issue.png and /dev/null differ diff --git a/opensource/workflow/images/existing_issue.png b/opensource/workflow/images/existing_issue.png deleted file mode 100644 index 0c49db6aa1..0000000000 Binary files a/opensource/workflow/images/existing_issue.png and /dev/null differ diff --git a/opensource/workflow/images/fixes_num.png b/opensource/workflow/images/fixes_num.png deleted file mode 100644 index 1b08554086..0000000000 Binary files a/opensource/workflow/images/fixes_num.png and /dev/null differ diff --git a/opensource/workflow/images/gordon.jpeg b/opensource/workflow/images/gordon.jpeg deleted file mode 100644 index 8a0df7d463..0000000000 Binary files a/opensource/workflow/images/gordon.jpeg and /dev/null differ diff --git a/opensource/workflow/images/issue_list.png b/opensource/workflow/images/issue_list.png deleted file mode 100644 index d6f5776adf..0000000000 Binary files a/opensource/workflow/images/issue_list.png and /dev/null differ diff --git a/opensource/workflow/images/latest_commits.png b/opensource/workflow/images/latest_commits.png deleted file mode 100644 index 7573d5433e..0000000000 Binary files a/opensource/workflow/images/latest_commits.png and /dev/null differ diff --git a/opensource/workflow/images/locate_branch.png b/opensource/workflow/images/locate_branch.png deleted file mode 100644 index b865cfcbf4..0000000000 Binary files a/opensource/workflow/images/locate_branch.png and /dev/null differ diff --git a/opensource/workflow/images/proposal.png b/opensource/workflow/images/proposal.png deleted file mode 100644 index 86a5ca2b3f..0000000000 Binary files a/opensource/workflow/images/proposal.png and /dev/null differ diff --git a/opensource/workflow/images/pull_request_made.png b/opensource/workflow/images/pull_request_made.png deleted file mode 100644 index 9eabe488ae..0000000000 Binary files a/opensource/workflow/images/pull_request_made.png and /dev/null differ diff --git a/opensource/workflow/images/to_from_pr.png b/opensource/workflow/images/to_from_pr.png deleted file mode 100644 index ddc553584b..0000000000 Binary files a/opensource/workflow/images/to_from_pr.png and /dev/null differ diff --git a/opensource/workflow/index.md b/opensource/workflow/index.md deleted file mode 100644 index 872d18deca..0000000000 --- a/opensource/workflow/index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -description: Describes Docker's communication channels -keywords: IRC, Google group, Twitter, blog, Stackoverflow -title: Contribution workflow ---- - -* [Understand how to contribute](make-a-contribution.md) -* [Find and claim an issue](find-an-issue.md) -* [Work on your issue](work-issue.md) -* [Create a pull request](create-pr.md) -* [Participate in the PR review](review-pr.md) -* [Advanced contributing](advanced-contributing.md) -* [Coding style checklist](coding-style.md) \ No newline at end of file diff --git a/opensource/workflow/make-a-contribution.md b/opensource/workflow/make-a-contribution.md deleted file mode 100644 index 8b858867d3..0000000000 --- a/opensource/workflow/make-a-contribution.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -description: Explains basic workflow for Docker contributions -keywords: contribute, maintainers, review, workflow, process -title: Understand how to contribute ---- - -Contributing is a process where you work with Docker maintainers and the -community to improve Docker. The maintainers are experienced contributors -who specialize in one or more Docker components. Maintainers play a big role -in reviewing contributions. - -There is a formal process for contributing. We try to keep our contribution -process simple so you'll want to contribute frequently. - - -## The basic contribution workflow - -In this guide, you work through Docker's basic contribution workflow by fixing a -single *beginner* issue in the `docker/docker` repository. The workflow -for fixing simple issues looks like this: - -![Simple process](images/existing_issue.png) - -All Docker repositories have code and documentation. You use this same workflow -for either content type. For example, you can find and fix doc or code issues. -Also, you can propose a new Docker feature or propose a new Docker tutorial. - -Some workflow stages do have slight differences for code or documentation -contributions. When you reach that point in the flow, we make sure to tell you. - - -## Where to go next - -Now that you know a little about the contribution process, go to the next section -to [find an issue you want to work on](find-an-issue.md). \ No newline at end of file diff --git a/opensource/workflow/review-pr.md b/opensource/workflow/review-pr.md deleted file mode 100644 index f45c8cbf42..0000000000 --- a/opensource/workflow/review-pr.md +++ /dev/null @@ -1,146 +0,0 @@ ---- -description: Basic workflow for Docker contributions -keywords: contribute, pull request, review, workflow, beginner, squash, commit -title: Participate in the PR review ---- - -Creating a pull request is nearly the end of the contribution process. At this -point, your code is reviewed both by our continuous integration (CI) systems and -by our maintainers. - -The CI system is an automated system. The maintainers are human beings that also -work on Docker. You need to understand and work with both the "bots" and the -"beings" to review your contribution. - -> **Note**: These guidelines apply to Docker code submissions. If you want to -> contribute to the Docker documentation itself, see the guidelines in the -> `docker.github.io` repository's -> [README.md](https://github.com/docker/docker.github.io). - -## How we process your review - -First to review your pull request is Gordon. Gordon is fast. He checks your -pull request (PR) for common problems like a missing signature. If Gordon finds a -problem, he'll send an email through your GitHub user account: - -![Gordon](images/gordon.jpeg) - -Our build bot system starts building your changes while Gordon sends any emails. - -The build system double-checks your work by compiling your code with Docker's master -code. Building includes running the same tests you ran locally. If you forgot -to run tests or missed something in fixing problems, the automated build is our -safety check. - -After Gordon and the bots, Docker maintainers look at your pull request and -provide feedback. The shortest comment you might see is `LGTM` which means -"Looks Good To Me". If you get an `LGTM`, that is a good thing, you passed that -review. - -For complex changes, maintainers may ask you questions or ask you to change -something about your submission. You are notified about all maintainer comments -on a PR, depending on the way you have configured Github to notify you. Any -GitHub user who participates in a PR receives an email. Participation includes -creating the PR, commenting on it, committing into someone else's PR, or being -at-mentioned in a comment. You can unsubscribe from notifications to a PR by -clicking the **Unsubscribe** button. - -Our maintainers are experienced Docker users and open source contributors. -They value your time and will try to work efficiently with you by keeping -their comments specific and brief. If they ask you to make a change, you'll -need to update your pull request with additional changes. - -## Update an existing pull request - -To update your existing pull request: - -1. Checkout the PR branch in your local repository. - - This is the branch associated with your request. - -2. Change one or more files and then stage your changes. - - The command syntax is: - - ```bash - $ git add - ``` - -3. Commit the change. - - ```bash - $ git commit --amend - ``` - - Git opens an editor containing your last commit message. - -4. Adjust your last comment to reflect this new change. - - ```none - - Added a new sentence per Anaud's suggestion - - Signed-off-by: Mary Anthony - - # Please enter the commit message for your changes. Lines starting - # with '#' will be ignored, and an empty message aborts the commit. - # On branch 11038-fix-rhel-link - # Your branch is up-to-date with 'origin/11038-fix-rhel-link'. - # - # Changes to be committed: - # modified: docs/installation/mac.md - # modified: docs/installation/rhel.md - ``` - -5. Force-push the change to your origin. - - Force-pushing is necessary because you amended your commit, and effectively - changed history. The command syntax is: - - ```bash - $ git push -f origin - ``` - -6. Open your browser to your pull request on GitHub. - - You should see your pull request now contains your newly pushed code. - -7. Add a comment to your pull request. - - GitHub only notifies PR participants when you comment. For example, you can - mention that you updated your PR. Your comment alerts the maintainers that - you made an update. - -A change requires LGTMs from an absolute majority of an affected component's -maintainers. For example, if you change `docs/` and `registry/` code, an -absolute majority of the `docs/` and the `registry/` maintainers must approve -your PR. Once you get approval, we merge your pull request into Docker's -`master` code branch. - -## After the merge - -It can take time to see a merged pull request in Docker's official release. -A master build is available almost immediately though. Docker builds and -updates its development binaries after each merge to `master`. - -1. Browse to [https://master.dockerproject.org/](https://master.dockerproject.org/){: target="_blank" class="_"}. - -2. Look for the binary appropriate to your system. - -3. Download and run the binary. - - You might want to run the binary in a container though. This - will keep your local host environment clean. - -Once you've verified everything merged, feel free to delete your feature branch -from your fork. -[See the GitHub help on deleting branches](https://help.github.com/articles/deleting-unused-branches/){: target="_blank" class="_"}. - -## Where to go next - -At this point, you have completed all the basic tasks in our contributors guide. -If you enjoyed contributing, let us know by completing another beginner -issue or two. We really appreciate the help. - -If you are very experienced and want to make a major change, go on to -[learn about advanced contributing](advanced-contributing.md). diff --git a/opensource/workflow/work-issue.md b/opensource/workflow/work-issue.md deleted file mode 100644 index 16f231d57b..0000000000 --- a/opensource/workflow/work-issue.md +++ /dev/null @@ -1,192 +0,0 @@ ---- -description: Basic workflow for Docker contributions -keywords: contribute, pull request, review, workflow, beginner, squash, commit -title: Work on your issue ---- - -The work you do depends on the specific issue you picked. -This section gives you a step-by-step workflow. Where appropriate, it provides -command examples. - -However, this is a generalized workflow, depending on your issue you may repeat -steps or even skip some. How much time the work takes depends on you --- you -could spend days or 30 minutes of your time. - -## How to work on your local branch - -Follow this workflow as you work: - -1. Review the appropriate style guide. - - If you are changing code, review the coding style guide. Changing documentation? Review the - documentation style guide. - -2. Make changes in your feature branch. - - Your feature branch is created in the last section. Here you use the - development container. If you are making a code change, you can mount your - source into a development container and iterate that way. For documentation - alone, you can work on your local host. - - Make sure you don't change files in the `vendor` directory and its - subdirectories; they contain third-party dependency code. Review if you forgot the details of - working with a container. - - -3. Test your changes as you work. - - If you have followed along with the guide, you know the `make test` target - runs the entire test suite and `make docs` builds the documentation. If you - forgot the other test targets, see the documentation for testing both code and - documentation. - -4. For code changes, add unit tests if appropriate. - - If you add new functionality or change existing functionality, you should - add a unit test also. Use the existing test files for inspiration. Aren't - sure if you need tests? Skip this step; you can add them later in the - process if necessary. - -5. Format your source files correctly. - - - - - - - - - - - - - - - - - - -
File typeHow to format
.go -

- Format .go files using the gofmt command. - For example, if you edited the docker.go file you would format the file - like this: -

-

$ gofmt -s -w docker.go

-

- Most file editors have a plugin to format for you. Check your editor's - documentation. -

-
.md and non-.go filesWrap lines to 80 characters.
- -6. List your changes. - - $ git status - On branch 11038-fix-rhel-link - Changes not staged for commit: - (use "git add ..." to update what will be committed) - (use "git checkout -- ..." to discard changes in working directory) - - modified: docs/installation/mac.md - modified: docs/installation/rhel.md - - The `status` command lists what changed in the repository. Make sure you see - the changes you expect. - -7. Add your change to Git. - - $ git add docs/installation/mac.md - $ git add docs/installation/rhel.md - - -8. Commit your changes making sure you use the `-s` flag to sign your work. - - $ git commit -s -m "Fixing RHEL link" - -9. Push your change to your repository. - - $ git push origin 11038-fix-rhel-link - Username for 'https://github.com': moxiegirl - Password for 'https://moxiegirl@github.com': - Counting objects: 60, done. - Compressing objects: 100% (7/7), done. - Writing objects: 100% (7/7), 582 bytes | 0 bytes/s, done. - Total 7 (delta 6), reused 0 (delta 0) - To https://github.com/moxiegirl/docker.git - * [new branch] 11038-fix-rhel-link -> 11038-fix-rhel-link - Branch 11038-fix-rhel-link set up to track remote branch 11038-fix-rhel-link from origin. - -## Review your branch on GitHub - -After you push a new branch, you should verify it on GitHub: - -1. Open your browser to GitHub. - -2. Go to your Docker fork. - -3. Select your branch from the dropdown. - - ![Find branch](images/locate_branch.png) - -4. Use the "Compare" button to compare the differences between your branch and master. - - Depending how long you've been working on your branch, your branch maybe - behind Docker's upstream repository. - -5. Review the commits. - - Make sure your branch only shows the work you've done. - -## Pull and rebase frequently - -You should pull and rebase frequently as you work. - -1. Return to the terminal on your local machine and checkout your - feature branch in your local `docker-fork` repository. - -2. Fetch any last minute changes from `docker/docker`. - - $ git fetch upstream master - From github.com:docker/docker - * branch master -> FETCH_HEAD - -3. Start an interactive rebase. - - $ git rebase -i upstream/master - -4. Rebase opens an editor with a list of commits. - - pick 1a79f55 Tweak some of the other text for grammar - pick 53e4983 Fix a link - pick 3ce07bb Add a new line about RHEL - -5. Replace the `pick` keyword with `squash` on all but the first commit. - - pick 1a79f55 Tweak some of the other text for grammar - squash 53e4983 Fix a link - squash 3ce07bb Add a new line about RHEL - - After you save the changes and quit from the editor, git starts - the rebase, reporting the progress along the way. Sometimes - your changes can conflict with the work of others. If git - encounters a conflict, it stops the rebase, and prints guidance - for how to correct the conflict. - -6. Edit and save your commit message. - - $ git commit -s - - Make sure your message includes your signature. - -7. Force push any changes to your fork on GitHub. - - $ git push -f origin 11038-fix-rhel-link - - -## Where to go next - -At this point, you should understand how to work on an issue. In the next -section, you [learn how to make a pull request](create-pr.md).