diff --git a/.dockerignore b/.dockerignore deleted file mode 100644 index f4ed19b06b..0000000000 --- a/.dockerignore +++ /dev/null @@ -1,22 +0,0 @@ -# XCode projects -.DS_Store -build/ -*.pbxuser -!default.pbxuser -*.mode1v3 -!default.mode1v3 -*.mode2v3 -!default.mode2v3 -*.perspectivev3 -!default.perspectivev3 -*.xcworkspace -!default.xcworkspace -xcuserdata -profile -*.moved-aside - -# Toolbox output -dist - -# Release -.sign diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000000..8f8a6218a7 --- /dev/null +++ b/.gitignore @@ -0,0 +1,53 @@ +###Go### + +# Compiled Object files, Static and Dynamic libs (Shared Objects) +*.o +*.a +*.so +*.swo +*.swp + +# Folders +_obj +_test + +# Architecture specific extensions/prefixes +*.[568vq] +[568vq].out + +*.cgo1.go +*.cgo2.c +_cgo_defun.c +_cgo_gotypes.go +_cgo_export.* + +_testmain.go + +*.exe +*.test + + +###OSX### + +.DS_Store +.AppleDouble +.LSOverride + +# Icon must ends with two \r. +Icon + + +# Thumbnails +._* +Thumb.db + +# Files that might appear on external disk +.Spotlight-V100 +.Trashes + +maintainers/maintainers +maintainers/MAINTAINERS + +# go generated files +maintainers/rules.go +maintainers/roles.go diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000000..29aa643f2c --- /dev/null +++ b/Dockerfile @@ -0,0 +1,34 @@ +FROM alpine +MAINTAINER Jessica Frazelle + +ENV PATH /go/bin:/usr/local/go/bin:$PATH +ENV GOPATH /go + +RUN apk update && apk add \ + ca-certificates \ + && rm -rf /var/cache/apk/* + +COPY . /go/src/github.com/docker/opensource + +RUN buildDeps=' \ + go \ + git \ + gcc \ + libc-dev \ + libgcc \ + ' \ + set -x \ + && apk update \ + && apk add $buildDeps \ + && cd /go/src/github.com/docker/opensource \ + && go get -d -v github.com/docker/opensource/maintainercollector \ + && go generate ./maintainercollector \ + && go build -o /usr/bin/maintainercollector ./maintainercollector \ + && apk del $buildDeps \ + && rm -rf /var/cache/apk/* \ + && rm -rf /go \ + && echo "Build complete." + +WORKDIR /root/maintainers + +ENTRYPOINT [ "maintainercollector" ] diff --git a/Jenkinsfile b/Jenkinsfile new file mode 100644 index 0000000000..86bce9d29c --- /dev/null +++ b/Jenkinsfile @@ -0,0 +1,8 @@ +// Only run on Linux atm +wrappedNode(label: 'linux') { + deleteDir() + stage "checkout" + checkout scm + + documentationChecker("docs") +} diff --git a/MAINTAINERS b/MAINTAINERS new file mode 100755 index 0000000000..6bdc8eaf91 --- /dev/null +++ b/MAINTAINERS @@ -0,0 +1,719 @@ +# +# THIS FILE IS AUTOGENERATED; SEE "./maintainercollector"! +# +# Docker projects maintainers file +# +# This file describes who runs the Docker project and how. +# This is a living document - if you see something out of date or missing, +# speak up! +# +# It is structured to be consumable by both humans and programs. +# To extract its contents programmatically, use any TOML-compliant +# parser. +[Rules] + + [Rules.maintainers] + + title = "What is a maintainer?" + + text = """ +There are different types of maintainers, with different responsibilities, but +all maintainers have 3 things in common: + +1) They share responsibility in the project's success. +2) They have made a long-term, recurring time investment to improve the project. +3) They spend that time doing whatever needs to be done, not necessarily what +is the most interesting or fun. + +Maintainers are often under-appreciated, because their work is harder to appreciate. +It's easy to appreciate a really cool and technically advanced feature. It's harder +to appreciate the absence of bugs, the slow but steady improvement in stability, +or the reliability of a release process. But those things distinguish a good +project from a great one. +""" + [Rules.adding-maintainers] + + title = "How are maintainers added?" + + text = """ +Maintainers are first and foremost contributors that have shown they are +committed to the long term success of a project. Contributors wanting to +become maintainers are expected to be deeply involved in contributing code, +pull request review, and triage of issues in the project for more than three +months. + +Just contributing does not make you a maintainer, it is about building trust +with the current maintainers of the project and being a person that they can +depend on and trust to make decisions in the best interest of the project. + +Maintainers are assigned per project (repository). Being a maintainer in +one project does not automatically make you a maintainer in other projects. + +Periodically, the existing maintainers curate a list of contributors that have +shown regular activity on the project over the prior months. From this +list, maintainer candidates are selected and proposed on the maintainers +mailing list. + +After a candidate has been announced on the maintainers mailing list, the +existing maintainers are given five business days to discuss the candidate, +raise objections and cast their vote. Candidates must be approved by the BDFL +and at least 66% of the current maintainers by adding their vote on the mailing +list. Only maintainers of the repository that the candidate is proposed for are +allowed to vote. The BDFL's vote is mandatory. + +If a candidate is approved, a maintainer will contact the candidate to +invite the candidate to open a pull request that adds the contributor to +the MAINTAINERS file. The candidate becomes a maintainer once the pull +request is merged. +""" + + [Rules.stepping-down-policy] + + title = "Stepping down policy" + + text = """ +Life priorities, interests, and passions can change. If you're a maintainer but +feel you must remove yourself from the list, inform other maintainers that you +intend to step down, and if possible, help find someone to pick up your work. +At the very least, ensure your work can be continued where you left off. + +After you've informed other maintainers, create a pull request to remove +yourself from the MAINTAINERS file. +""" + + [Rules.inactive-maintainers] + + title = "Removal of inactive maintainers" + + text = """ +Similar to the procedure for adding new maintainers, existing maintainers can +be removed from the list if they do not show significant activity on the +project. Periodically, the maintainers review the list of maintainers and their +activity over the last three months. + +If a maintainer has shown insufficient activity over this period, a neutral +person will contact the maintainer to ask if they want to continue being +a maintainer. If the maintainer decides to step down as a maintainer, they +open a pull request to be removed from the MAINTAINERS file. + +If the maintainer wants to remain a maintainer, but is unable to perform the +required duties they can be removed with a vote by the BDFL and at least 66% of +the current maintainers. The BDFL's vote is mandatory. An e-mail is sent to the +mailing list, inviting maintainers of the project to vote. The voting period is +five business days. Issues related to a maintainer's performance should be +discussed with them among the other maintainers so that they are not surprised +by a pull request removing them. +""" + + [Rules.alumni] + + title = "Alumni" + + text = """ +Projects can opt to keep a list of former maintainers in the MAINTAINERS file. +Instead of removing a maintainer from the file when they step down, the maintainer +is moved to the alumni list (`[Org.Alumni]`). People on this list have +no official capacity in the project, it's a way to say "thank you" for the +work they have done for the project. +""" + + [Rules.bdfl] + + title = "The Benevolent dictator for life (BDFL)" + + text = """ +Docker follows the timeless, highly efficient and totally unfair system +known as [Benevolent dictator for +life](https://en.wikipedia.org/wiki/Benevolent_Dictator_for_Life), with +yours truly, Solomon Hykes, in the role of BDFL. This means that all +decisions are made, by default, by Solomon. Since making every decision +myself would be highly un-scalable, in practice decisions are spread +across multiple maintainers. + +Ideally, the BDFL role is like the Queen of England: awesome crown, but not +an actual operational role day-to-day. The real job of a BDFL is to NEVER GO AWAY. +Every other rule can change, perhaps drastically so, but the BDFL will always +be there, preserving the philosophy and principles of the project, and keeping +ultimate authority over its fate. This gives us great flexibility in experimenting +with various governance models, knowing that we can always press the "reset" button +without fear of fragmentation or deadlock. See the US congress for a counter-example. + +BDFL daily routine: + +* Is the project governance stuck in a deadlock or irreversibly fragmented? + * If yes: refactor the project governance +* Are there issues or conflicts escalated by core? + * If yes: resolve them +* Go back to polishing that crown. +""" + + [Rules.decisions] + + title = "How are decisions made?" + + text = """ +Short answer: EVERYTHING IS A PULL REQUEST. + +Docker is an open-source project with an open design philosophy. This +means that the repository is the source of truth for EVERY aspect of the +project, including its philosophy, design, road map, and APIs. *If it's +part of the project, it's in the repo. If it's in the repo, it's part of +the project.* + +As a result, all decisions can be expressed as changes to the +repository. An implementation change is a change to the source code. An +API change is a change to the API specification. A philosophy change is +a change to the philosophy manifesto, and so on. + +All decisions affecting Docker, big and small, follow the same 3 steps: + +* Step 1: Open a pull request. Anyone can do this. + +* Step 2: Discuss the pull request. Anyone can do this. + +* Step 3: Merge or refuse the pull request. Who does this depends on the nature +of the pull request and which areas of the project it affects. See *review flow* +for details. + +Because Docker is such a large and active project, it's important for everyone to know +who is responsible for deciding what. That is determined by a precise set of rules. + +* For every *decision* in the project, the rules should designate, in a deterministic way, +who should *decide*. + +* For every *problem* in the project, the rules should designate, in a deterministic way, +who should be responsible for *fixing* it. + +* For every *question* in the project, the rules should designate, in a deterministic way, +who should be expected to have the *answer*. +""" + + [Rules.review] + + title = "Review flow" + + text = """ +Pull requests should be processed according to the following flow: + +* For each subsystem affected by the change, the maintainers of the subsystem must approve or refuse it. +It is the responsibility of the subsystem maintainers to process patches affecting them in a timely +manner. + +* If the change affects areas of the code which are not part of a subsystem, +or if subsystem maintainers are unable to reach a timely decision, it must be approved by +the core maintainers. + +* If the change affects the UI or public APIs, or if it represents a major change in architecture, +the architects must approve or refuse it. + +* If the change affects the operations of the project, it must be approved or rejected by +the relevant operators. + +* If the change affects the governance, philosophy, goals or principles of the project, +it must be approved by BDFL. +""" + + [Rules.DCO] + + title = "Helping contributors with the DCO" + + text = """ +The [DCO or `Sign your work`]( +https://github.com/docker/docker/blob/master/CONTRIBUTING.md#sign-your-work) +requirement is not intended as a roadblock or speed bump. + +Some Docker contributors are not as familiar with `git`, or have used a web based +editor, and thus asking them to `git commit --amend -s` is not the best way forward. + +In this case, maintainers can update the commits based on clause (c) of the DCO. The +most trivial way for a contributor to allow the maintainer to do this, is to add +a DCO signature in a pull requests's comment, or a maintainer can simply note that +the change is sufficiently trivial that it does not substantially change the existing +contribution - i.e., a spelling change. + +When you add someone's DCO, please also add your own to keep a log. +""" + + [Rules."no direct push"] + + title = "I'm a maintainer. Should I make pull requests too?" + + text = """ +Yes. Nobody should ever push to master directly. All changes should be +made through a pull request. +""" + + [Rules.meta] + + title = "How is this process changed?" + + text = "Just like everything else: by making a pull request :)" + + +# Current project roles +[Roles] + + [Roles.bdfl] + + person = "shykes" + + [Roles."Chief Architect"] + + person = "shykes" + + text = """ +The chief architect is responsible for the overall integrity of the technical architecture +across all subsystems, and the consistency of APIs and UI. + +Changes to UI, public APIs and overall architecture (for example a plugin system) must +be approved by the chief architect. +""" + + [Roles."Chief Maintainer"] + + person = "crosbymichael" + + text = """ +The chief maintainer is responsible for all aspects of quality for the project including +code reviews, usability, stability, security, performance, etc. +The most important function of the chief maintainer is to lead by example. On the first +day of a new maintainer, the best advice should be "follow the C.M.'s example and you'll +be fine". +""" + + [Roles."Community Manager"] + + person = "theadactyl" + + text = """ +The community manager is responsible for serving the project community, including users, +contributors and partners. This involves: + - facilitating communication between maintainers, contributors and users + - organizing contributor and maintainer events + - helping new contributors get involved + - anything the project community needs to be successful + +The community manager is a point of contact for any contributor who has questions, concerns +or feedback about project operations. +""" + + +[Org] + [Org.Curators] + People = ["programmerq", "thajeztah", "amitshukla"] + [Org."Docs maintainers"] + People = ["jamtur01", "moxiegirl", "sven", "thajeztah", "sfsmithcha"] + [Org.boot2docker] + People = ["ehazlett", "tianon"] + [Org.compose] + People = ["aanand", "bfirsh", "dnephin", "mnowster"] + [Org.containerd] + People = ["crosbymichael", "tonistiigi", "mlaventure"] + [Org.datakit] + People = ["samoht", "talex5"] + [Org.distribution] + People = ["aaronlehmann", "dmcgowan", "dmp42", "richardscothern", "shykes", "stevvooe"] + [Org.docker] + People = ["aaronlehmann", "calavera", "coolljt0725", "cpuguy83", "crosbymichael", "duglin", "estesp", "icecrime", "jhowardmsft", "justincormack", "lk4d4", "mavenugo", "mhbauer", "runcom", "tianon", "tibor", "tonistiigi", "unclejack", "vdemeester"] + [Org.docker-bench-security] + People = ["diogomonica", "konstruktoid"] + [Org.docker-credential-helpers] + People = ["aaronlehmann", "calavera", "coolljt0725", "cpuguy83", "crosbymichael", "dnephin", "dongluochen", "duglin", "estesp", "icecrime", "jhowardmsft", "lk4d4", "mavenugo", "mhbauer", "runcom", "stevvooe", "thajeztah", "tianon", "tibor", "tonistiigi", "unclejack", "vdemeester", "vieux"] + [Org.docker-py] + People = ["aanand", "dnephin", "mnowster", "mpetazzoni", "shin-"] + [Org.dockercraft] + People = ["aduermael", "davetucker", "gdevillele"] + [Org.engine-api] + People = ["aaronlehmann", "calavera", "coolljt0725", "cpuguy83", "crosbymichael", "dnephin", "dongluochen", "duglin", "estesp", "icecrime", "jhowardmsft", "lk4d4", "mavenugo", "mhbauer", "runcom", "stevvooe", "thajeztah", "tianon", "tibor", "tonistiigi", "unclejack", "vdemeester", "vieux"] + [Org.go-connections] + People = ["calavera"] + [Org.go-events] + People = ["aaronlehmann", "aluzzardi", "lk4d4", "stevvooe"] + [Org.go-p9p] + People = ["aduermael", "djs55", "frenchben", "justincormack", "stevvooe"] + [Org.go-plugins-helpers] + People = ["calavera", "dave-tucker", "runcom"] + [Org.go-units] + People = ["calavera"] + [Org.hyperkit] + People = ["avsm", "djs55", "dsheets", "gdevillele", "ijc25", "justincormack", "magnuss", "rneugeba", "samoht"] + [Org.kitematic] + People = ["elesant", "frenchben", "jeffdm", "mchiang0610"] + [Org.leadership] + People = ["abronan"] + [Org.leeroy] + People = ["calavera", "jfrazelle"] + [Org.libchan] + People = ["dmcgowan", "shykes"] + [Org.libcompose] + People = ["aanand", "aduermael", "dnephin", "ibuildthecloud", "joshwget", "gdevillele", "vdemeester"] + [Org.libkv] + People = ["abronan", "aluzzardi", "sanimej", "vieux"] + [Org.libnetwork] + People = ["aboch", "lk4d4", "icecrime", "mrjana", "mavenugo", "sanimej", "chenchun"] + [Org.machine] + People = ["dgageot", "ehazlett", "jeanlaurent", "nathanleclaire"] + [Org.migrator] + People = ["mbentley"] + [Org.notary] + People = ["cyli", "diogomonica", "dmcgowan", "endophage", "nathanmccauley", "riyazdf"] + [Org.spdystream] + People = ["dmcgowan"] + [Org.swarm] + People = ["abronan", "allencloud", "aluzzardi", "chanwit", "dongluochen", "jimmyxian", "mhbauer", "nishanttotla", "vieux"] + [Org.swarm-frontends] + People = ["abronan", "amitshukla", "samalba"] + [Org.swarmkit] + People = ["aaronlehmann", "abronan", "aluzzardi", "amitshukla", "diogomonica", "dongluochen", "lk4d4", "mrjana", "nishanttotla", "stevvooe", "tonistiigi", "vieux"] + [Org.toolbox] + People = ["jeffdm", "lisean106", "mchiang0610"] + [Org."v1.10-migrator"] + People = ["tonistiigi"] + [Org.vpnkit] + People = ["avsm", "djs55", "samoht", "yomimono"] + +[People] + [People.aanand] + Name = "Aanand Prasad" + Email = "aanand@docker.com" + GitHub = "aanand" + [People.aaronlehmann] + Name = "Aaron Lehmann" + Email = "aaron.lehmann@docker.com" + GitHub = "aaronlehmann" + [People.aboch] + Name = "Alessandro Boch" + Email = "aboch@docker.com" + GitHub = "aboch" + [People.abronan] + Name = "Alexandre Beslic" + Email = "abronan@docker.com" + GitHub = "abronan" + [People.aduermael] + Name = "Adrien Duermael" + Email = "adrien@docker.com" + GitHub = "aduermael" + [People.allencloud] + Name = "Allen Sun" + Email = "allen.sun@daocloud.io" + GitHub = "allencloud" + [People.aluzzardi] + Name = "Andrea Luzzardi" + Email = "al@docker.com" + GitHub = "aluzzardi" + [People.amitshukla] + Name = "Amit Shukla" + Email = "amit.shukla@docker.com" + GitHub = "amitshukla" + [People.avsm] + Name = "Anil Madhavapeddy" + Email = "anil@recoil.org" + GitHub = "avsm" + [People.bfirsh] + Name = "Ben Firshman" + Email = "ben@firshman.co.uk" + GitHub = "bfirsh" + [People.brianbland] + Name = "Brian Bland" + Email = "brian.bland@docker.com" + GitHub = "BrianBland" + [People.calavera] + Name = "David Calavera" + Email = "david.calavera@gmail.com" + GitHub = "calavera" + [People.chanwit] + Name = "Chanwit Kaewkasi" + Email = "chanwit@gmail.com" + GitHub = "chanwit" + [People.chenchun] + Name = "Chun Chen" + Email = "ramichen@tencent.com" + GitHub = "chenchun" + [People.coolljt0725] + Name = "Lei Jitang" + Email = "leijitang@huawei.com" + GitHub = "coolljt0725" + [People.cpuguy83] + Name = "Brian Goff" + Email = "cpuguy83@gmail.com" + GitHub = "cpuguy83" + [People.crosbymichael] + Name = "Michael Crosby" + Email = "crosbymichael@gmail.com" + GitHub = "crosbymichael" + [People.cyli] + Name = "Ying Li" + Email = "ying.li@docker.com" + GitHub = "cyli" + [People.dave-tucker] + Name = "Dave Tucker" + Email = "dt@docker.com" + GitHub = "dave-tucker" + [People.davetucker] + Name = "Dave Tucker" + Email = "dave.tucker@docker.com" + GitHub = "dave-tucker" + [People.dgageot] + Name = "David Gageot" + Email = "david.gageot@docker.com" + GitHub = "dgageot" + [People.diogomonica] + Name = "Diogo Monica" + Email = "diogo@docker.com" + GitHub = "diogomonica" + [People.djs55] + Name = "David Scott" + Email = "dave.scott@docker.com" + GitHub = "djs55" + [People.dmcgowan] + Name = "Derek McGowan" + Email = "derek@docker.com" + GitHub = "dmcgowan" + [People.dmp42] + Name = "Olivier Gambier" + Email = "olivier@docker.com" + GitHub = "dmp42" + [People.dnephin] + Name = "Daniel Nephin" + Email = "dnephin@gmail.com" + GitHub = "dnephin" + [People.dongluochen] + Name = "Dongluo Chen" + Email = "dong@docker.com" + GitHub = "dongluochen" + [People.dsheets] + Name = "David Sheets" + Email = "dsheets@docker.com" + GitHub = "dsheets" + [People.duglin] + Name = "Doug Davis" + Email = "dug@us.ibm.com" + GitHub = "duglin" + [People.ehazlett] + Name = "Evan Hazlett" + Email = "ejhazlett@gmail.com" + GitHub = "ehazlett" + [People.elesant] + Name = "Sean Li" + Email = "mail@shang.li" + GitHub = "elesant" + [People.endophage] + Name = "David Lawrence" + Email = "david.lawrence@docker.com" + GitHub = "endophage" + [People.erikh] + Name = "Erik Hollensbe" + Email = "erik@docker.com" + GitHub = "erikh" + [People.estesp] + Name = "Phil Estes" + Email = "estesp@linux.vnet.ibm.com" + GitHub = "estesp" + [People.frenchben] + Name = "Ben French" + Email = "frenchben@docker.com" + GitHub = "FrenchBen" + [People.gdevillele] + Name = "Gaetan de Villele" + Email = "gaetan@docker.com" + GitHub = "gdevillele" + [People.ibuildthecloud] + Name = "Darren Shepherd" + Email = "darren@rancher.com" + GitHub = "ibuildthecloud" + [People.icecrime] + Name = "Arnaud Porterie" + Email = "arnaud@docker.com" + GitHub = "icecrime" + [People.ijc25] + Name = "Ian Campbell" + Email = "ian.campbell@docker.com" + GitHub = "ijc25" + [People.jamtur01] + Name = "James Turnbull" + Email = "james@lovedthanlost.net" + GitHub = "jamtur01" + [People.jeanlaurent] + Name = "Jean-Laurent de Morlhon" + Email = "jeanlaurent@docker.com>" + GitHub = "jeanlaurent" + [People.jeffdm] + Name = "Jeff Morgan" + Email = "jmorgan@docker.com" + GitHub = "jeffdm" + [People.jfrazelle] + Name = "Jessie Frazelle" + Email = "acidburn@docker.com" + GitHub = "jfrazelle" + [People.jhowardmsft] + Name = "John Howard" + Email = "jhoward@microsoft.com" + GitHub = "jhowardmsft" + [People.jimmyxian] + Name = "Xian Chaobo" + Email = "xianchaobo@huawei.com" + GitHub = "jimmyxian" + [People.joshwget] + Name = "Josh Curl" + Email = "josh@rancher.com" + GitHub = "joshwget" + [People.justincormack] + Name = "Justin Cormack" + Email = "justin.cormack@docker.com" + GitHub = "justincormack" + [People.konstruktoid] + Name = "Thomas Sjögren" + Email = "thomas.sjogren@outlook.com" + GitHub = "konstruktoid" + [People.lisean106] + Name = "Sean Li" + Email = "sean@docker.com" + GitHub = "lisean106" + [People.lk4d4] + Name = "Alexander Morozov" + Email = "lk4d4@docker.com" + GitHub = "lk4d4" + [People.magnuss] + Name = "Magnus Skjegstad" + Email = "magnus@skjegstad.com" + GitHub = "MagnusS" + [People.mavenugo] + Name = "Madhu Venugopal" + Email = "madhu@docker.com" + GitHub = "mavenugo" + [People.mbentley] + Name = "Matt Bentley" + Email = "matt.bentley@docker.com" + GitHub = "mbentley" + [People.mchiang0610] + Name = "Michael Chiang" + Email = "mchiang@docker.com" + GitHub = "mchiang0610" + [People.mhbauer] + Name = "Morgan Bauer" + Email = "mbauer@us.ibm.com" + GitHub = "mhbauer" + [People.mlaventure] + Name = "Kenfe-Mickaël Laventure" + Email = "mickael.laventure@docker.com" + GitHub = "mlaventure" + [People.mnowster] + Name = "Mazz Mosley" + Email = "mazz@houseofmnowster.com" + GitHub = "mnowster" + [People.moxiegirl] + Name = "Mary Anthony" + Email = "mary.anthony@docker.com" + GitHub = "moxiegirl" + [People.mpetazzoni] + Name = "Maxime Petazzoni" + Email = "maxime.petazzoni@bulix.org" + GitHub = "mpetazzoni" + [People.mrjana] + Name = "Jana Radhakrishnan" + Email = "mrjana@docker.com" + GitHub = "mrjana" + [People.nathanleclaire] + Name = "Nathan LeClaire" + Email = "nathan.leclaire@docker.com" + GitHub = "nathanleclaire" + [People.nathanmccauley] + Name = "Nathan McCauley" + Email = "nathan.mccauley@docker.com" + GitHub = "nathanmccauley" + [People.nishanttotla] + Name = "Nishant Totla" + Email = "nishanttotla@gmail.com" + GitHub = "nishanttotla" + [People.programmerq] + Name = "Jeff Anderson" + Email = "jeff@docker.com" + GitHub = "programmerq" + [People.richardscothern] + Name = "Richard Scothern" + Email = "richard.scothern@gmail.com" + GitHub = "richardscothern" + [People.riyazdf] + Name = "Riyaz Faizullabhoy" + Email = "riyaz@docker.com" + GitHub = "riyazdf" + [People.rneugeba] + Name = "Rolf Neugebauer" + Email = "rolf.neugebauer@docker.com" + GitHub = "rneugeba" + [People.runcom] + Name = "Antonio Murdaca" + Email = "runcom@redhat.com" + GitHub = "runcom" + [People.samalba] + Name = "Sam Alba" + Email = "sam.alba@docker.com" + GitHub = "samalba" + [People.samoht] + Name = "Thomas Gazagnaire" + Email = "thomas@gazagnaire.org" + GitHub = "samoht" + [People.sanimej] + Name = "Santhosh Manohar" + Email = "santhosh@docker.com" + GitHub = "sanimej" + [People.shin-] + Name = "Joffrey F" + Email = "joffrey@docker.com" + GitHub = "shin-" + [People.shykes] + Name = "Solomon Hykes" + Email = "solomon@docker.com" + GitHub = "shykes" + [People.stevvooe] + Name = "Stephen Day" + Email = "stephen.day@docker.com" + GitHub = "stevvooe" + [People.sven] + Name = "Sven Dowideit" + Email = "SvenDowideit@home.org.au" + GitHub = "SvenDowideit" + [People.talex5] + Name = "Thomas Leonard" + Email = "thomas.leonard@docker.com" + GitHub = "talex5" + [People.thajeztah] + Name = "Sebastiaan van Stijn" + Email = "github@gone.nl" + GitHub = "thaJeztah" + [People.tianon] + Name = "Tianon Gravi" + Email = "admwiggin@gmail.com" + GitHub = "tianon" + [People.tibor] + Name = "Tibor Vass" + Email = "tibor@docker.com" + GitHub = "tiborvass" + [People.tonistiigi] + Name = "Tõnis Tiigi" + Email = "tonis@docker.com" + GitHub = "tonistiigi" + [People.unclejack] + Name = "Cristian Staretu" + Email = "cristian.staretu@gmail.com" + GitHub = "unclejack" + [People.vbatts] + Name = "Vincent Batts" + Email = "vbatts@redhat.com" + GitHub = "vbatts" + [People.vdemeester] + Name = "Vincent Demeester" + Email = "vincent@sbr.pm" + GitHub = "vdemeester" + [People.vieux] + Name = "Victor Vieux" + Email = "vieux@docker.com" + GitHub = "vieux" + [People.vishh] + Name = "Vishnu Kannan" + Email = "vishnuk@google.com" + GitHub = "vishh" + [People.yomimono] + Name = "Mindy Preston" + Email = "mindy.preston@docker.com" + GitHub = "yomimono" diff --git a/Makefile b/Makefile new file mode 100644 index 0000000000..84cbe0ba70 --- /dev/null +++ b/Makefile @@ -0,0 +1,5 @@ +.PHONY: maintainers + +maintainers: + @docker build --rm --force-rm -t docker/maintainers . + @docker run --rm -v $(CURDIR):/root/maintainers docker/maintainers diff --git a/README.md b/README.md new file mode 100644 index 0000000000..c523e12a12 --- /dev/null +++ b/README.md @@ -0,0 +1,4 @@ +This repo contains documentation and scripts related to the management of Open Source at Docker. + +The compiled list of maintainers of all Docker subprojects can be found at +[MAINTAINERS](MAINTAINERS). diff --git a/docs/Dockerfile b/docs/Dockerfile new file mode 100644 index 0000000000..fff39f3314 --- /dev/null +++ b/docs/Dockerfile @@ -0,0 +1,9 @@ +FROM docs/base:oss +MAINTAINER Docker Docs + +ENV PROJECT=opensource + +# To get the git info for this repo +COPY . /src +RUN rm -rf /docs/content/$PROJECT/ +COPY . /docs/content/$PROJECT/ diff --git a/docs/FAQ.md b/docs/FAQ.md new file mode 100644 index 0000000000..7051c9bb47 --- /dev/null +++ b/docs/FAQ.md @@ -0,0 +1,125 @@ + + +# 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?](#how-do-i-set-my-signature:cb7f612e17aad7eb26c06709ef92a867) +- [How do I track changes from the docker repo upstream?](#how-do-i-track-changes-from-the-docker-repo-upstream:cb7f612e17aad7eb26c06709ef92a867) +- [How do I format my Go code?](#how-do-i-format-my-go-code:cb7f612e17aad7eb26c06709ef92a867) +- [What is the pre-pull request checklist?](#what-is-the-pre-pull-request-checklist:cb7f612e17aad7eb26c06709ef92a867) +- [How should I comment my code?](#how-should-i-comment-my-code:cb7f612e17aad7eb26c06709ef92a867) +- [How do I rebase my feature branch?](#how-do-i-rebase-my-feature-branch:cb7f612e17aad7eb26c06709ef92a867) + +## How do I set my signature {#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/docker/docker.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 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. Squash 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 diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000000..56916a1582 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,40 @@ +.PHONY: all build default docs docs-build docs-shell shell test + +# to allow `make DOCSDIR=docs docs-shell` (to create a bind mount in docs) +DOCS_MOUNT := $(if $(DOCSDIR),-v $(CURDIR)/$(DOCSDIR):/$(DOCSDIR)) + +# to allow `make DOCSPORT=9000 docs` +DOCSPORT := 8000 + +# Get the IP ADDRESS +DOCKER_IP=$(shell python -c "import urlparse ; print urlparse.urlparse('$(DOCKER_HOST)').hostname or ''") +HUGO_BASE_URL=$(shell test -z "$(DOCKER_IP)" && echo localhost || echo "$(DOCKER_IP)") +HUGO_BIND_IP=0.0.0.0 + +GIT_BRANCH := $(shell git rev-parse --abbrev-ref HEAD 2>/dev/null) +GIT_BRANCH_CLEAN := $(shell echo $(GIT_BRANCH) | sed -e "s/[^[:alnum:]]/-/g") +DOCKER_DOCS_IMAGE := docker-docs$(if $(GIT_BRANCH_CLEAN),:$(GIT_BRANCH_CLEAN)) + +DOCKER_RUN_DOCS := docker run --rm -it $(DOCS_MOUNT) -e AWS_S3_BUCKET -e NOCACHE + +# for some docs workarounds (see below in "docs-build" target) +GITCOMMIT := $(shell git rev-parse --short HEAD 2>/dev/null) + +default: docs + +docs: docs-build + $(DOCKER_RUN_DOCS) -p $(if $(DOCSPORT),$(DOCSPORT):)8000 -e DOCKERHOST "$(DOCKER_DOCS_IMAGE)" hugo server --port=$(DOCSPORT) --baseUrl=$(HUGO_BASE_URL) --bind=$(HUGO_BIND_IP) + +docs-draft: docs-build + $(DOCKER_RUN_DOCS) -p $(if $(DOCSPORT),$(DOCSPORT):)8000 -e DOCKERHOST "$(DOCKER_DOCS_IMAGE)" hugo server --buildDrafts="true" --port=$(DOCSPORT) --baseUrl=$(HUGO_BASE_URL) --bind=$(HUGO_BIND_IP) + + +docs-shell: docs-build + $(DOCKER_RUN_DOCS) -p $(if $(DOCSPORT),$(DOCSPORT):)8000 "$(DOCKER_DOCS_IMAGE)" bash + + +docs-build: + docker build -t "$(DOCKER_DOCS_IMAGE)" . + +test: docs-build + $(DOCKER_RUN_DOCS) -e DOCKERHOST "$(DOCKER_DOCS_IMAGE)" diff --git a/docs/code.md b/docs/code.md new file mode 100644 index 0000000000..8a3cf92c0a --- /dev/null +++ b/docs/code.md @@ -0,0 +1,87 @@ + + +# Quickstart code or doc 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. + +If you want to contribute to the `docker/docker` repository you should be +familiar with or invested in learning Go or the Markdown language. 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 or documentation. +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 contributors guide. + +1. Get the software 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. + + Your Git configuration can make it easier for you to contribute. + Configuration is especially key if are new to contributing or to Docker. + +3. Learn to work with the Docker development container. + + Docker developers run `docker` in `docker`. If you are a geek, + this is a pretty cool experience. +4. Claim an issue to work on. + + We created a filter listing all open + and unclaimed issues for Docker. + +5. Work on the +issue. + + 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. + + Also, remember to always **sign your commits** as you work! To sign your + commits, include the `-s` flag in your commit like this: + + $ git commit -s -m "Add commit with signature example" + + If you don't sign Gordon will get you! + +6. Create a +pull request. + + 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 have also have checklist that describes [what each pull request + needs](#what-is-the-pre-pull-request-checklist). + + +7. Participate in the pull request review till a successful +merge. diff --git a/docs/doc-style.md b/docs/doc-style.md new file mode 100644 index 0000000000..5d856bd39f --- /dev/null +++ b/docs/doc-style.md @@ -0,0 +1,283 @@ + + +# Docker documentation: style & 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/docker/docker/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 at least a "16th" grade level (meaning they have a +university degree). You can use a [readability +tester](https://readability-score.com/) to help guide your judgement. 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](#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 (e.g., menu text or button text) should appear in "double +quotes". The text should take the exact same capitalisation, etc. as appears in +the GUI. E.g., Click "Continue" to save the settings. + +Text that refers to a keyboard command or hotkey is capitalized (e.g., 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 cut-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). + +## 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](#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/docs/get-help.md b/docs/get-help.md new file mode 100644 index 0000000000..09fc5e1320 --- /dev/null +++ b/docs/get-help.md @@ -0,0 +1,219 @@ + + + + +# Where to chat or get help + +There are several communications channels you can use to chat with Docker +community members and developers. + + + + + + + + + + + + + + + + + + + +
Forum + The Docker Community Forum is for contributors and others working with Docker software or projects. +
Internet Relay Chat (IRC) + +

+ IRC a direct line to our most knowledgeable Docker users. + The #docker and #docker-dev group on + chat.freenode.net. IRC was first created in 1988. + So, it is a rich chat protocol but it can overwhelm new users. You can search + our chat archives. +

+ Use our IRC quickstart guide below for easy ways to get started with IRC. +
Twitter + You can follow Docker's twitter + to get updates on our products. You can also tweet us questions or just + share blogs or stories. +
Stack Overflow + Stack Overflow has over 7000K Docker questions listed. We regularly + monitor Docker questions + and so do many other knowledgeable Docker users. +
+ + +# IRC Quickstart + +The following instructions show you how to register with two web based IRC +tools. Use one illustrated here or find another. While these instructions are +only for two IRC web clients there are many IRC Clients available on most +platforms. + +## Webchat + +Using Webchat from Freenode.net is a quick and easy way to get chatting. To +register: + +1. In your browser open https://webchat.freenode.net + + ![Login to webchat screen](images/irc_connect.png) + +2. Fill out the form. + + + + + + + + + + + + + + +
NicknameThe short name you want to be known as on IRC chat channels.
Channels#docker
reCAPTCHAUse the value provided.
+ +3. Click on the "Connect" button. + + The browser connects you to Webchat. You'll see a lot of text. At the bottom of + the Webchat web page is a command line bar. Just above the command line bar + a message is shown asking you to register. + + ![Registration needed screen](images/irc_after_login.png) + +4. Register your nickname by entering the following command in the +command line bar: + + /msg NickServ REGISTER yourpassword youremail@example.com + + ![Registering screen](images/register_nic.png) + + This command line bar is also the entry field that you will use for entering + chat messages into IRC chat channels after you have registered and joined a + chat channel. + + After entering the REGISTER command, an email is sent to the email address + that you provided. This email will contain instructions for completing + your registration. + +5. Open your email client and look for the email. + + ![Login screen](images/register_email.png) + +6. Back in the browser, complete the registration according to the email +by entering the following command into the webchat command line bar: + + /msg NickServ VERIFY REGISTER yournickname somecode + + Your nickname is now registered to chat on freenode.net. + +[Jump ahead to tips to join a docker channel and start chatting](#tips) + +## IRCCloud + +IRCCloud is a web-based IRC client service that is hosted in the cloud. This is +a Freemium product, meaning the free version is limited and you can pay for more +features. To use IRCCloud: + +1. Select the following link: + Join the #docker channel on chat.freenode.net + + The following web page is displayed in your browser: + + ![IRCCloud Register screen](images/irccloud-join.png) + +2. If this is your first time using IRCCloud enter a valid email address in the +form. People who have already registered with IRCCloud can select the "sign in +here" link. Additionally, people who are already registered with IRCCloud may +have a cookie stored on their web browser that enables a quick start "let's go" +link to be shown instead of the above form. In this case just select the +"let's go" link and [jump ahead to start chatting](#start-chatting) + +3. After entering your email address in the form, check your email for an invite +from IRCCloud and follow the instructions provided in the email. + +4. After following the instructions in your email you should have an IRCCloud +Client web page in your browser: + + ![IRCCloud](images/irccloud-register-nick.png) + + The message shown above may appear indicating that you need to register your + nickname. + +5. To register your nickname enter the following message into the command line bar +at the bottom of the IRCCloud Client: + + /msg NickServ REGISTER yourpassword youremail@example.com + + This command line bar is for chatting and entering in IRC commands. + +6. Check your email for an invite to freenode.net: + + ![Login screen](images/register_email.png) + +7. Back in the browser, complete the registration according to the email. + + /msg NickServ VERIFY REGISTER yournickname somecode + +## Tips + +The procedures in this section apply to both IRC clients. + +### Set a nickname + +Next time you return to log into chat, you may need to re-enter your password +on the command line using this command: + + /msg NickServ identify + +With Webchat if you forget or lose your password you'll need to join the +`#freenode` channel and request them to reset it for you. + +### Join a Docker Channel + +Join the `#docker` group using the following command in the command line bar of +your IRC Client: + + /j #docker + +You can also join the `#docker-dev` group: + + /j #docker-dev + +### Start chatting + +To ask questions to the group just type messages in the command line bar: + + ![Web Chat Screen](images/irc_chat.png) + +## Learning more about IRC + +This quickstart was meant to get you up and into IRC very quickly. If you find +IRC useful there is more to learn. Drupal, another open source project, +has +written some documentation about using IRC for their project +(thanks Drupal!). diff --git a/docs/governance/board-profiles.md b/docs/governance/board-profiles.md new file mode 100644 index 0000000000..fb88f73030 --- /dev/null +++ b/docs/governance/board-profiles.md @@ -0,0 +1,72 @@ + + + +# Project Leadership + +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) diff --git a/docs/governance/conduct-code.md b/docs/governance/conduct-code.md new file mode 100644 index 0000000000..e802aa9732 --- /dev/null +++ b/docs/governance/conduct-code.md @@ -0,0 +1,46 @@ + + +# 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/docs/governance/dgab-info.md b/docs/governance/dgab-info.md new file mode 100644 index 0000000000..57f4128e9f --- /dev/null +++ b/docs/governance/dgab-info.md @@ -0,0 +1,198 @@ + + +# 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)\. diff --git a/docs/governance/images/hackday-600px.jpg b/docs/governance/images/hackday-600px.jpg new file mode 100644 index 0000000000..f393185ae9 Binary files /dev/null and b/docs/governance/images/hackday-600px.jpg differ diff --git a/docs/governance/index.md b/docs/governance/index.md new file mode 100644 index 0000000000..f473129a0a --- /dev/null +++ b/docs/governance/index.md @@ -0,0 +1,18 @@ + + + +# Governance + +* [Docker Governance Advisory Board](dgab-info.md ) +* [Board member profiles](board-profiles.md ) +* [Code of conduct](conduct-code.md) diff --git a/docs/images/bonus.png b/docs/images/bonus.png new file mode 100644 index 0000000000..a902bf8f73 Binary files /dev/null and b/docs/images/bonus.png differ diff --git a/docs/images/docker-friends.png b/docs/images/docker-friends.png new file mode 100644 index 0000000000..55b0148fe5 Binary files /dev/null and b/docs/images/docker-friends.png differ diff --git a/docs/images/gordon.jpeg b/docs/images/gordon.jpeg new file mode 100644 index 0000000000..8a0df7d463 Binary files /dev/null and b/docs/images/gordon.jpeg differ diff --git a/docs/images/irc_after_login.png b/docs/images/irc_after_login.png new file mode 100644 index 0000000000..79496c806d Binary files /dev/null and b/docs/images/irc_after_login.png differ diff --git a/docs/images/irc_chat.png b/docs/images/irc_chat.png new file mode 100644 index 0000000000..6266020f65 Binary files /dev/null and b/docs/images/irc_chat.png differ diff --git a/docs/images/irc_connect.png b/docs/images/irc_connect.png new file mode 100644 index 0000000000..f411aabcac Binary files /dev/null and b/docs/images/irc_connect.png differ diff --git a/docs/images/irc_login.png b/docs/images/irc_login.png new file mode 100644 index 0000000000..a7a1dc7eb4 Binary files /dev/null and b/docs/images/irc_login.png differ diff --git a/docs/images/irccloud-join.png b/docs/images/irccloud-join.png new file mode 100644 index 0000000000..068b2c4b20 Binary files /dev/null and b/docs/images/irccloud-join.png differ diff --git a/docs/images/irccloud-register-nick.png b/docs/images/irccloud-register-nick.png new file mode 100644 index 0000000000..60c8560565 Binary files /dev/null and b/docs/images/irccloud-register-nick.png differ diff --git a/docs/images/register_email.png b/docs/images/register_email.png new file mode 100644 index 0000000000..02ef4cd271 Binary files /dev/null and b/docs/images/register_email.png differ diff --git a/docs/images/register_nic.png b/docs/images/register_nic.png new file mode 100644 index 0000000000..16cf05a396 Binary files /dev/null and b/docs/images/register_nic.png differ diff --git a/docs/images/triage-label.png b/docs/images/triage-label.png new file mode 100644 index 0000000000..2a2351c0d1 Binary files /dev/null and b/docs/images/triage-label.png differ diff --git a/docs/images/tutorials.png b/docs/images/tutorials.png new file mode 100644 index 0000000000..be7cb2f3df Binary files /dev/null and b/docs/images/tutorials.png differ diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000000..b327aa3db0 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,22 @@ + + + +# Open Source at Docker + +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. + +- [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 dont' want to code. +- [Governance](governance/index.md) describes the proper conduct and who defines it. diff --git a/docs/kitematic/create_pr.md b/docs/kitematic/create_pr.md new file mode 100644 index 0000000000..7b24039294 --- /dev/null +++ b/docs/kitematic/create_pr.md @@ -0,0 +1,65 @@ + + +# Create a pull request (PR) +Make sure you follow the rebase guidelines before you make a pull request. +Rebasing helps verify that your commit is clean, and allows for an easier and faster merge of your code. + +Once you've cleaned up your commits: + +1. Push your code to your repository under the same name as your local branch (in the case of this example, 1191-branch). + + $ git push origin 1191-branch:1191-branch + +2. Open a web browser to your fork on GitHub. + + You should see the latest activity from your branch. + +3. Click **Compare & pull request**. + + The system displays the pull request dialog. + + ![Pull Request dialog](images/pr_compare.png) + + The pull request compares your changes to the `master` branch on the + `kitematic/kitematic` repository. + +4. Edit the pull request 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/pr_describe_issue.png) + +5. 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/pr_commits_expected.png) + +6. Click **Create pull request**. + + The system creates the request and opens it for you in the `kitematic/kitematic` + repository. + + ![Pull request made](images/pr_pull_request_made.png) + + +## Where to go next + +Congratulations! You've created your first pull request to Kitematic! + +The next step in this process is to participate your PR's review. To learn more, and try another development exercise, see [where to learn more](next_steps.md) . + + diff --git a/docs/kitematic/find_issue.md b/docs/kitematic/find_issue.md new file mode 100644 index 0000000000..d8b14d110f --- /dev/null +++ b/docs/kitematic/find_issue.md @@ -0,0 +1,47 @@ + + + +# Find an issue on GitHub +Currently, the Kitematic GUI shows the name of a selected container, but not the ID. The tour shows you how to improve the GUI by adding the container ID to the 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. + +2. Click the **Issues** link. + + A list of the open issues appears. + + ![Open issues](images/list_open_issues.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. + + For this exercise we will select the issue #1191 Missing container id. + +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. + +6. Make a note of the issue number; you will need it for later. + +## Where to go next + +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.) diff --git a/docs/kitematic/get_started.md b/docs/kitematic/get_started.md new file mode 100644 index 0000000000..e89ef06959 --- /dev/null +++ b/docs/kitematic/get_started.md @@ -0,0 +1,37 @@ + + +## Contribute to Kitematic + +Kitematic is an open source project that simplifies the Docker experience. It +automates Docker installation and setup, and provides an interactive graphical +user interface (GUI) for working with containers. You can use Kitematic to create, run, and manage Docker containers, and find public images on Docker Hub. + +![Kitematic GUI](images/gui-splash-hub.png) + +See the Kitematic user guide to learn more about it from a user perspective. + +## We welcome your contributions! +We'd like to see Kitematic evolve +with community contributed add-ons, extensions, themes, plug-ins, and cool, new +features. +## Start the developer tour +If you're new to working with Docker open source projects or new to +the Kitematic codebase, this quick tour will help you get started. Follow along with these steps to set up your Kitematic development environment and practice working on an example issue. + +1. [Find a Kitematic issue on GitHub and fork](find_issue.md) +2. [Set up your Kitematic development environment and clone the repository](set_up_dev.md) +3. [Develop in Kitematic (work on an issue)](work_issue.md) +4. [Review your branch and create a pull request (PR)](create_pr.md) +5. [Where to learn more](next_steps.md) + +## Where to go next +[Find an issue on GitHub](find_issue.md) to get started. diff --git a/docs/kitematic/images/gui-no-id.png b/docs/kitematic/images/gui-no-id.png new file mode 100644 index 0000000000..01fa4096d3 Binary files /dev/null and b/docs/kitematic/images/gui-no-id.png differ diff --git a/docs/kitematic/images/gui-splash-hub.png b/docs/kitematic/images/gui-splash-hub.png new file mode 100644 index 0000000000..0f266de703 Binary files /dev/null and b/docs/kitematic/images/gui-splash-hub.png differ diff --git a/docs/kitematic/images/kitematic_gui_container_id.png b/docs/kitematic/images/kitematic_gui_container_id.png new file mode 100644 index 0000000000..56678ebc93 Binary files /dev/null and b/docs/kitematic/images/kitematic_gui_container_id.png differ diff --git a/docs/kitematic/images/list_open_issues.png b/docs/kitematic/images/list_open_issues.png new file mode 100644 index 0000000000..723d10b4b4 Binary files /dev/null and b/docs/kitematic/images/list_open_issues.png differ diff --git a/docs/kitematic/images/nvm_install.jpeg b/docs/kitematic/images/nvm_install.jpeg new file mode 100644 index 0000000000..5a89be4bfe Binary files /dev/null and b/docs/kitematic/images/nvm_install.jpeg differ diff --git a/docs/kitematic/images/pr_commits_expected.png b/docs/kitematic/images/pr_commits_expected.png new file mode 100644 index 0000000000..561f68c178 Binary files /dev/null and b/docs/kitematic/images/pr_commits_expected.png differ diff --git a/docs/kitematic/images/pr_compare.png b/docs/kitematic/images/pr_compare.png new file mode 100644 index 0000000000..506d4057f0 Binary files /dev/null and b/docs/kitematic/images/pr_compare.png differ diff --git a/docs/kitematic/images/pr_describe_issue.png b/docs/kitematic/images/pr_describe_issue.png new file mode 100644 index 0000000000..265dfb64a6 Binary files /dev/null and b/docs/kitematic/images/pr_describe_issue.png differ diff --git a/docs/kitematic/images/pr_latest_commits.png b/docs/kitematic/images/pr_latest_commits.png new file mode 100644 index 0000000000..791683a5c5 Binary files /dev/null and b/docs/kitematic/images/pr_latest_commits.png differ diff --git a/docs/kitematic/images/pr_pull_request_made.png b/docs/kitematic/images/pr_pull_request_made.png new file mode 100644 index 0000000000..580e8351e0 Binary files /dev/null and b/docs/kitematic/images/pr_pull_request_made.png differ diff --git a/docs/kitematic/images/settings-code-example.png b/docs/kitematic/images/settings-code-example.png new file mode 100644 index 0000000000..8d2cb4ad53 Binary files /dev/null and b/docs/kitematic/images/settings-code-example.png differ diff --git a/docs/kitematic/index.md b/docs/kitematic/index.md new file mode 100644 index 0000000000..914659ca5a --- /dev/null +++ b/docs/kitematic/index.md @@ -0,0 +1,19 @@ + + +# Contribute to Kitematic +* [Get started] (get_started.md) +* [Find an issue on GitHub](find_issue.md) +* [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) diff --git a/docs/kitematic/next_steps.md b/docs/kitematic/next_steps.md new file mode 100644 index 0000000000..a3b8165ab1 --- /dev/null +++ b/docs/kitematic/next_steps.md @@ -0,0 +1,44 @@ + + +# 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. + +As you learned in the previous exercise, adding the container id to the container Settings tab is fairly simple. + +Let's provide another missing piece of information for Kitematic users: + +"_When I look at an active container in Kitematic, I want to know what command the container is currently running_." + +![An active container in Kitematic](images/kitematic_gui_container_id.png) + +In a terminal window, users can get this by looking at running containers with: `docker ps` + +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: + +* + README First + +* Quick Start contribution + +* Understand how to contribute diff --git a/docs/kitematic/set_up_dev.md b/docs/kitematic/set_up_dev.md new file mode 100644 index 0000000000..8d76011bcf --- /dev/null +++ b/docs/kitematic/set_up_dev.md @@ -0,0 +1,156 @@ + + +# Set up for Kitematic development + +Kitematic is built on top of: + +* Electron + +* Node.js + +* React and AltJS (which follows the Flux pattern) + +## Download and install NVM + +To get started, you will need to install Node.js v4.2.1. Using Node Version Manager (NVM) makes the Node.js install easy. + +### Windows: +1. Download latest release + +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; +the above installer link will have an uninstaller available. + + ![windows installer](images/nvm_install.jpeg) + +### Mac OSX/Linux: + +1. Open a terminal window + +2. Copy and paste the following install script: + + curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.29.0/install.sh | bash + +3. To activate nvm, close the terminal window and re-open a new one. + + (Alternatively, you can source nvm from your current shell with the command `. ~/.nvm/nvm.sh` ) + +(To learn more about working with NVM, see Mac OSX/Linux official nvm repo, Windows official nvm repo, and How To Install Node.js with NVM ON A VPS) + +## Install Node.js + +1. Install the proper Node.js version. + + $ nvm install v4.2.1 + +2. Make this version the default. + + $ nvm alias default v4.2.1 + +3. Run `node --version` to confirm that you are now using the proper Node.js version. + + $ node --version + +## Fork the master branch of Kitematic + +To fork the master branch of Kitematic: + +1. Go to the docker/kitematic repository . + +2. Click **Fork** in the upper right corner of the GitHub interface. + + GitHub forks the repository to your GitHub account. The original + `docker/kitematic` repository becomes a new fork `YOUR_ACCOUNT/kitematic` + under your account. + +3. 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. 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. + +## Clone your repository locally and create a branch + +To clone your repository and create a branch for the issue: + +1. Open a terminal window on your local host and change to your home directory. + + $ cd ~ + + In Windows, you'll work in your Docker Quickstart Terminal window instead of Powershell or a `cmd` window. + +2. Create a directory for your new repository and change into that directory. + +3. From the root of your repository, clone the fork to your local host. + + $ git clone https://github.com/YOUR_USERNAME/kitematic.git + +4. Create and checkout a branch for the issue you will be working on. + + $ git checkout -b 1191-branch + + As previously mentioned, issue #1191 is set up as an example to use for this exercise. + +## Set up your signature and upstream remote +You can set your signature globally or locally. + +1. Set your `user.name` for the repository. + + $ git config --local user.name "FirstName LastName" + +2. Set your `user.email` for the repository. + + $ git config --local user.email "emailname@mycompany.com" + +3. Check the result in your `git` configuration. + + $ git config --local --list + +4. Set your local repository to track changes upstream, on the `kitematic` +repository. + + $ 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. + +1. Verify that the package manager is running and check the version (at the time of this writing, v2.14.7). + + $ npm --version + +2. Install the package dependencies. + + $ npm install + +3. From the root of your kitematic repository, use the package manager to start Kitematic and confirm everything went well. + + $ npm start + +All of the core files in Kitematic are in the `src` folder, which then +follows the AltJS structure of: +``` +kitematic/ +|--src/ + |--actions/ + | |--MyActions.js + |--stores/ + | |--MyStore.js + |--components/ + | |--MyComponent.react.js +``` +The `components` folder is where the layout files are, the `stores` represent the application logic and `actions` are the dispatcher for actions taken within the `components`. + +## Where to go next +You are ready to start working on the issue. Go to [Develop in Kitematic (work +on an issue)](work_issue.md). diff --git a/docs/kitematic/work_issue.md b/docs/kitematic/work_issue.md new file mode 100644 index 0000000000..f79b9998a8 --- /dev/null +++ b/docs/kitematic/work_issue.md @@ -0,0 +1,79 @@ + + +## 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.) + +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. + +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): + + ``` + return ( +
+ ... + ``` + (line ~200) + +3. Above this code we will create a javascript variable that will allow us to display our container id: + + ``` + let shortId = ( +
+

Container Id

+
+ +
+
+ ); + ``` + + This snippet has been saved as a GitHub gist. + +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: + + ``` + return ( +
+ {rename} + {shortId} + ``` + At this point, the updated code should look similar to this: + + ![Javascript to display container id in kitematic](images/settings-code-example.png) + +5. Save the code changes, re-start Kitematic. + + $ npm start + + Now, the container ID should show on the General Settings tab, along with the container name. + + ![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.* + +6. You can close the Kitematic application now, and kill the running process in the terminal via CTRL+c. + +7. Stage your changes by adding them. + + $ git add src/components/ContainerSettingsGeneral.react.js + +8. Commit your code changes with a comment that explains what this fixes or closes. + + $ 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.) + +## Where to go next +At this point, you are ready to [Review your branch and create a pull request](create_pr.md) to merge your new feature into Kitematic. diff --git a/docs/project/images/box.png b/docs/project/images/box.png new file mode 100644 index 0000000000..642385ae68 Binary files /dev/null and b/docs/project/images/box.png differ diff --git a/docs/project/images/branch-sig.png b/docs/project/images/branch-sig.png new file mode 100644 index 0000000000..b30f007ba6 Binary files /dev/null and b/docs/project/images/branch-sig.png differ diff --git a/docs/project/images/checked.png b/docs/project/images/checked.png new file mode 100644 index 0000000000..93ab2be9b3 Binary files /dev/null and b/docs/project/images/checked.png differ diff --git a/docs/project/images/contributor-edit.png b/docs/project/images/contributor-edit.png new file mode 100644 index 0000000000..52737d7b46 Binary files /dev/null and b/docs/project/images/contributor-edit.png differ diff --git a/docs/project/images/copy_url.png b/docs/project/images/copy_url.png new file mode 100644 index 0000000000..a715019ed8 Binary files /dev/null and b/docs/project/images/copy_url.png differ diff --git a/docs/project/images/existing_issue.snagproj b/docs/project/images/existing_issue.snagproj new file mode 100644 index 0000000000..05ae2b0ccf Binary files /dev/null and b/docs/project/images/existing_issue.snagproj differ diff --git a/docs/project/images/fork_docker.png b/docs/project/images/fork_docker.png new file mode 100644 index 0000000000..f7c557cd4f Binary files /dev/null and b/docs/project/images/fork_docker.png differ diff --git a/docs/project/images/fresh_container.png b/docs/project/images/fresh_container.png new file mode 100644 index 0000000000..7f69f2d3a5 Binary files /dev/null and b/docs/project/images/fresh_container.png differ diff --git a/docs/project/images/git_bash.png b/docs/project/images/git_bash.png new file mode 100644 index 0000000000..153fd2fbb9 Binary files /dev/null and b/docs/project/images/git_bash.png differ diff --git a/docs/project/images/give_try.png b/docs/project/images/give_try.png new file mode 100644 index 0000000000..c049527616 Binary files /dev/null and b/docs/project/images/give_try.png differ diff --git a/docs/project/images/in_room.png b/docs/project/images/in_room.png new file mode 100644 index 0000000000..4fdec81b9c Binary files /dev/null and b/docs/project/images/in_room.png differ diff --git a/docs/project/images/include_gcc.png b/docs/project/images/include_gcc.png new file mode 100644 index 0000000000..e48f50cdf9 Binary files /dev/null and b/docs/project/images/include_gcc.png differ diff --git a/docs/project/images/list_example.png b/docs/project/images/list_example.png new file mode 100644 index 0000000000..c7a4d227cc Binary files /dev/null and b/docs/project/images/list_example.png differ diff --git a/docs/project/images/path_variable.png b/docs/project/images/path_variable.png new file mode 100644 index 0000000000..52f197a5e9 Binary files /dev/null and b/docs/project/images/path_variable.png differ diff --git a/docs/project/images/proposal.snagproj b/docs/project/images/proposal.snagproj new file mode 100644 index 0000000000..c9ad49d0e7 Binary files /dev/null and b/docs/project/images/proposal.snagproj differ diff --git a/docs/project/images/red_notice.png b/docs/project/images/red_notice.png new file mode 100644 index 0000000000..8839723a37 Binary files /dev/null and b/docs/project/images/red_notice.png differ diff --git a/docs/project/images/three_running.png b/docs/project/images/three_running.png new file mode 100644 index 0000000000..cf6d25f2dc Binary files /dev/null and b/docs/project/images/three_running.png differ diff --git a/docs/project/images/three_terms.png b/docs/project/images/three_terms.png new file mode 100644 index 0000000000..7caa6ac6e3 Binary files /dev/null and b/docs/project/images/three_terms.png differ diff --git a/docs/project/images/windows-env-vars.png b/docs/project/images/windows-env-vars.png new file mode 100644 index 0000000000..68d00e9080 Binary files /dev/null and b/docs/project/images/windows-env-vars.png differ diff --git a/docs/project/images/windows-mingw.png b/docs/project/images/windows-mingw.png new file mode 100644 index 0000000000..b1d15e6b1d Binary files /dev/null and b/docs/project/images/windows-mingw.png differ diff --git a/docs/project/index.md b/docs/project/index.md new file mode 100644 index 0000000000..25c2fdd17d --- /dev/null +++ b/docs/project/index.md @@ -0,0 +1,20 @@ + + +# 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) diff --git a/docs/project/set-up-dev-env.md b/docs/project/set-up-dev-env.md new file mode 100644 index 0000000000..eb4ce4ea12 --- /dev/null +++ b/docs/project/set-up-dev-env.md @@ -0,0 +1,308 @@ + + +# 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 (with +Docker Machine if their machine is Mac OS X). 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. + + ```bash + $ docker ps -a + ``` + + You should see something similar to the following: + + ```bash + 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: + + ```bash + $ 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. + + ```bash + $ docker images + ``` + + You should see something similar to the following: + + ```bash + 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: + + ```bash + $ 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. + + Mac 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. + +2. Change into the root of the `docker-fork` repository. + + ```bash + $ 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. + + ```bash + $ 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. + + ```bash + $ make shell + ``` + + The command returns informational messages as it runs. The first build may + take a few minutes to create an image. Using the instructions in the + `Dockerfile`, the build may need to download source and other images. A + successful build returns a final message and opens a Bash shell into the + container. + + ```bash + 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/docker/docker/bundles" -t "docker-dev:dry-run-test" bash + root@f31fa223770f:/go/src/github.com/docker/docker# + ``` + + At this point, your prompt reflects the container's BASH shell. + +5. List the contents of the current directory (`/go/src/github.com/docker/docker`). + + You should see the image's source from the `/go/src/github.com/docker/docker` + directory. + + ![List example](images/list_example.png) + +6. Make a `docker` binary. + + ```bash + root@a8b2885ab900:/go/src/github.com/docker/docker# 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. Copy the binary to the container's `/usr/bin` directory. + + ```bash + root@a8b2885ab900:/go/src/github.com/docker/docker# cp bundles/1.12.0-dev/binary-client/docker* /usr/bin + root@a8b2885ab900:/go/src/github.com/docker/docker# cp bundles/1.12.0-dev/binary-daemon/docker* /usr/bin + ``` + +8. Start the Engine daemon running in the background. + + ```bash + root@a8b2885ab900:/go/src/github.com/docker/docker# docker daemon -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. + +9. Inside your container, check your Docker version. + + ```bash + root@5f8630b873fe:/go/src/github.com/docker/docker# 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. + + ```bash + root@5f8630b873fe:/go/src/github.com/docker/docker# docker run hello-world + ``` + +11. List the image you just downloaded. + + ```bash + root@5f8630b873fe:/go/src/github.com/docker/docker# docker images + ``` + +12. Open another terminal on your local host. + +13. List the container running your development container. + + ```bash + 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-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 a 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 shell` command mounted your local Docker repository source into +your Docker container. When you start to developing 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. + + ```bash + $ 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 `api/client/attach.go` file. + +4. Edit the command's help message. + + For example, you can edit this line: + + ```go + noStdin := cmd.Bool([]string{"-no-stdin"}, false, "Do not attach STDIN") + ``` + + And change it to this: + + ```go + noStdin := cmd.Bool([]string{"-no-stdin"}, false, "Do not attach STDIN (standard in)") + ``` + +5. Save and close the `api/client/attach.go` file. + +6. Go to your running development container. + +7. Remake the binary and copy it to `usr/bin` + +8. Restart the Docker daemon with the new binary. + +9. View your change by display the `attach` help. + + ```bash + root@b0cb4f22715d:/go/src/github.com/docker/docker# 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 develpment 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/docs/project/set-up-git.md b/docs/project/set-up-git.md new file mode 100644 index 0000000000..70cb6b1d6f --- /dev/null +++ b/docs/project/set-up-git.md @@ -0,0 +1,287 @@ + + +# 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/docker/docker.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/docker/docker.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/docker/docker.git (fetch) + upstream https://github.com/docker/docker.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. + + $ git branch + * dry-run-test + master + + The current branch has an * (asterisk) marker. So, these results shows 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. + + ``` + $ 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. + +8. 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. + + 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. + +9. Open your browser to GitHub. + +10. Navigate to your Docker fork. + +11. 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/docs/project/software-req-win.md b/docs/project/software-req-win.md new file mode 100644 index 0000000000..2f3d2bb3db --- /dev/null +++ b/docs/project/software-req-win.md @@ -0,0 +1,265 @@ + + + +# Get the required software for Windows + +This page explains how to get the software you need to use a a Windows Server +2012 or Windows 8 machine for Docker development. Before you begin contributing +you must have: + +- a GitHub account +- Git for Windows (msysGit) +- TDM-GCC, a compiler suite for Windows +- MinGW (tar and xz) +- Go language + +> **Note**: This installation procedure refers to the `C:\` drive. If you system's main drive +is `D:\` you'll need to substitute that in where appropriate in these +instructions. + +## 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 for Windows + +Git for Windows includes several tools including msysGit, which is a build +environment. The environment contains the tools you need for development such as +Git and a Git Bash shell. + +1. Browse to the [Git for Windows](https://msysgit.github.io/) download page. + +2. Click **Download**. + + Windows prompts you to save the file to your machine. + +3. Run the saved file. + + The system displays the **Git Setup** wizard. + +4. Click the **Next** button to move through the wizard and accept all the defaults. + +5. Click **Finish** when you are done. + +## Task 3. Install TDM-GCC + +TDM-GCC is a compiler suite for Windows. You'll use this suite to compile the +Docker Go code as you develop. + +1. Browse to + [tdm-gcc download page](http://tdm-gcc.tdragon.net/download). + +2. Click on the latest 64-bit version of the package. + + Windows prompts you to save the file to your machine + +3. Set up the suite by running the downloaded file. + + The system opens the **TDM-GCC Setup** wizard. + +4. Click **Create**. + +5. Click the **Next** button to move through the wizard and accept all the defaults. + +6. Click **Finish** when you are done. + + +## Task 4. Install MinGW (tar and xz) + +MinGW is a minimalist port of the GNU Compiler Collection (GCC). In this +procedure, you first download and install the MinGW installation manager. Then, +you use the manager to install the `tar` and `xz` tools from the collection. + +1. Browse to MinGW + [SourceForge](http://sourceforge.net/projects/mingw/). + +2. Click **Download**. + + Windows prompts you to save the file to your machine + +3. Run the downloaded file. + + The system opens the **MinGW Installation Manager Setup Tool** + +4. Choose **Install** install the MinGW Installation Manager. + +5. Press **Continue**. + + The system installs and then opens the MinGW Installation Manager. + +6. Press **Continue** after the install completes to open the manager. + +7. Select **All Packages > MSYS Base System** from the left hand menu. + + The system displays the available packages. + +8. Click on the the **msys-tar bin** package and choose **Mark for Installation**. + +9. Click on the **msys-xz bin** package and choose **Mark for Installation**. + +10. Select **Installation > Apply Changes**, to install the selected packages. + + The system displays the **Schedule of Pending Actions Dialog**. + + ![windows-mingw](images/windows-mingw.png) + +11. Press **Apply** + + MingGW installs the packages for you. + +12. Close the dialog and the MinGW Installation Manager. + + +## Task 5. Set up your environment variables + +You'll need to add the compiler to your `Path` environment variable. + +1. Open the **Control Panel**. + +2. Choose **System and Security > System**. + +3. Click the **Advanced system settings** link in the sidebar. + + The system opens the **System Properties** dialog. + +3. Select the **Advanced** tab. + +4. Click **Environment Variables**. + + The system opens the **Environment Variables dialog** dialog. + +5. Locate the **System variables** area and scroll to the **Path** + variable. + + ![windows-mingw](images/path_variable.png) + +6. Click **Edit** to edit the variable (you can also double-click it). + + The system opens the **Edit System Variable** dialog. + +7. Make sure the `Path` includes `C:\TDM-GCC64\bin` + + ![include gcc](images/include_gcc.png) + + If you don't see `C:\TDM-GCC64\bin`, add it. + +8. Press **OK** to close this dialog. + +9. Press **OK** twice to close out of the remaining dialogs. + +## Install Go and cross-compile it + +In this section, you install the Go language. Then, you build the source so that it can cross-compile for `linux/amd64` architectures. + +1. Open [Go Language download](http://golang.org/dl/) page in your browser. + +2. Locate and click the latest `.msi` installer. + + The system prompts you to save the file. + +3. Run the installer. + + The system opens the **Go Programming Language Setup** dialog. + +4. Select all the defaults to install. + +5. Press **Finish** to close the installation dialog. + +6. Start a command prompt. + +7. Change to the Go `src` directory. + + cd c:\Go\src + +8. Set the following Go variables + + c:\Go\src> set GOOS=linux + c:\Go\src> set GOARCH=amd64 + +9. Compile the source. + + c:\Go\src> make.bat + + Compiling the source also adds a number of variables to your Windows environment. + +## Task 6. Get the Docker repository + +In this step, you start a Git `bash` terminal and get the Docker source code +from GitHub. + +1. Locate the **Git Bash** program and start it. + + Recall that **Git Bash** came with the Git for Windows installation. **Git + Bash** just as it sounds allows you to run a Bash terminal on Windows. + + ![Git Bash](images/git_bash.png) + +2. Change to the root directory. + + $ cd /c/ + +3. Make a `gopath` directory. + + $ mkdir gopath + +4. Go get the `docker/docker` repository. + + $ go.exe get github.com/docker/docker package github.com/docker/docker + imports github.com/docker/docker + imports github.com/docker/docker: no buildable Go source files in C:\gopath\src\github.com\docker\docker + + In the next steps, you create environment variables for you Go paths. + +5. Open the **Control Panel** on your system. + +6. Choose **System and Security > System**. + +7. Click the **Advanced system settings** link in the sidebar. + + The system opens the **System Properties** dialog. + +8. Select the **Advanced** tab. + +9. Click **Environment Variables**. + + The system opens the **Environment Variables dialog** dialog. + +10. Locate the **System variables** area and scroll to the **Path** + variable. + +11. Click **New**. + + Now you are going to create some new variables. These paths you'll create in the next procedure; but you can set them now. + +12. Enter `GOPATH` for the **Variable Name**. + +13. For the **Variable Value** enter the following: + + C:\gopath;C:\gopath\src\github.com\docker\docker\vendor + + +14. Press **OK** to close this dialog. + + The system adds `GOPATH` to the list of **System Variables**. + +15. Press **OK** twice to close out of the remaining dialogs. + + +## 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/docs/project/software-required.md b/docs/project/software-required.md new file mode 100644 index 0000000000..e1774c9e93 --- /dev/null +++ b/docs/project/software-required.md @@ -0,0 +1,109 @@ + + +# Get the required software for Linux or OS X + +This page explains how to get the software you need to use a Linux or OS X +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 Mac OS X 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 OS X 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). diff --git a/docs/project/test-and-docs.md b/docs/project/test-and-docs.md new file mode 100644 index 0000000000..25a4bd6bfe --- /dev/null +++ b/docs/project/test-and-docs.md @@ -0,0 +1,342 @@ + + +# 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. +The target's name is simply `test`. The `Makefile` contains several targets for +testing: + + + + + + + + + + + + + + + + + + + + + + + +
TargetWhat this target does
testRun the unit, integration and docker-py tests.
test-unitRun just the unit tests.
test-integration-cliRun the test for the integration command line interface.
test-docker-pyRun the tests for Docker API client.
+ +Running the entire test suite on your current repository can take a half an hour +or more. To run the test suite, do the following: + +1. Open a terminal on your local host. + +2. Change to the root 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: + + ```bash + PASS: docker_cli_pull_test.go:133: DockerHubPullSuite.TestPullClientDisconnect 1.127s + PASS: docker_cli_pull_test.go:16: DockerHubPullSuite.TestPullFromCentralRegistry 1.049s + PASS: docker_cli_pull_test.go:65: DockerHubPullSuite.TestPullFromCentralRegistryImplicitRefParts 9.795s + PASS: docker_cli_pull_test.go:42: DockerHubPullSuite.TestPullNonExistingImage 2.158s + PASS: docker_cli_pull_test.go:92: DockerHubPullSuite.TestPullScratchNotAllowed 0.044s + OK: 918 passed, 13 skipped + PASS + coverage: 72.9% of statements + ok github.com/docker/docker/integration-cli 1638.553s + ---> Making bundle: .integration-daemon-stop (in bundles/1.9.0-dev/test-integration-cli) + ++++ cat bundles/1.9.0-dev/test-integration-cli/docker.pid + +++ kill 9453 + +++ /etc/init.d/apparmor stop + * Clearing AppArmor profiles cache + ...done. + All profile caches have been cleared, but no profiles have been unloaded. + Unloading profiles will leave already running processes permanently + unconfined, which can lead to unexpected situations. + + To set a process to complain mode, use the command line tool + 'aa-complain'. To really tear down all profiles, run the init script + with the 'teardown' option." + + ---> Making bundle: test-docker-py (in bundles/1.9.0-dev/test-docker-py) + ---> Making bundle: .integration-daemon-start (in bundles/1.9.0-dev/test-docker-py) + +++ /etc/init.d/apparmor start + * Starting AppArmor profiles + Skipping profile in /etc/apparmor.d/disable: usr.sbin.rsyslogd + ...done. + +++ exec docker daemon --debug --host unix:///go/src/github.com/docker/docker/bundles/1.9.0-dev/test-docker-py/docker.sock --storage-driver overlay --exec-driver native --pidfile bundles/1.9.0-dev/test-docker-py/docker.pid --userland-proxy=true + ..............s..............s...................................... + ---------------------------------------------------------------------- + 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/docker/docker dry-run-test /bin/bash + ``` + +3. Run the tests using the `hack/make.sh` script. + + ```bash + root@5f8630b873fe:/go/src/github.com/docker/docker# 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/docker/docker# 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. + + $ 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: + + $ 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. + + $ 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: + + $ TESTFLAGS='-check.f DockerSuite.TestBuild*' make test-integration-cli + +To run the same test inside your Docker development container, you do this: + + root@5f8630b873fe:/go/src/github.com/docker/docker# 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. + + $ cd /c/gopath/src/github.com/docker/docker + +3. Set `DOCKER_REMOTE_DAEMON` as follows: + + $ 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: + + $ export DOCKER_TEST_HOST=tcp://213.124.23.200:2376 + +5. Make the binary and run the tests: + + $ 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 + + $ 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 + + $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 under `docs`. The content is +written using extended Markdown. We use the static generator MkDocs to build Docker's +documentation. Of course, you don't need to install this generator +to build the documentation, it is included with container. + +You should always check your documentation for grammar and spelling. The best +way to do this is with an online grammar checker. + +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. The build starts a container +and loads the documentation into a server. As long as this container runs, you +can browse the docs. + +1. In a terminal, change to the root of your `docker-fork` repository. + + $ cd ~/repos/docker-fork + +2. Make sure you are in your feature branch. + + $ git status + On branch dry-run-test + Your branch is up-to-date with 'origin/dry-run-test'. + nothing to commit, working directory clean + +3. Build the documentation. + + $ make docs + + When the build completes, you'll see a final output message similar to the + following: + + Successfully built ee7fe7553123 + docker run --rm -it -e AWS_S3_BUCKET -e NOCACHE -p 8000:8000 "docker-docs:dry-run-test" mkdocs serve + Running at: http://0.0.0.0:8000/ + Live reload enabled. + Hold ctrl+c to quit. + +4. Enter the URL in your browser. + + If you are using Docker Machine, replace the default localhost address + (0.0.0.0) with your DOCKERHOST value. You can get this value at any time by + entering `docker-machine ip ` at the command line. + +5. Once in the documentation, look for the red notice to verify you are seeing the correct build. + + ![Beta documentation](images/red_notice.png) + +6. Navigate to your new or changed document. + +7. Review both the content and the links. + +8. Return to your terminal and exit out of the running documentation container. + + +## 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/docs/project/who-written-for.md b/docs/project/who-written-for.md new file mode 100644 index 0000000000..72a13e183a --- /dev/null +++ b/docs/project/who-written-for.md @@ -0,0 +1,65 @@ + + +# 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 at 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 OS X](software-required.md). If you are +on Windows, see [get the required software for Windows](software-req-win.md). diff --git a/docs/ways/community.md b/docs/ways/community.md new file mode 100644 index 0000000000..be042327e5 --- /dev/null +++ b/docs/ways/community.md @@ -0,0 +1,51 @@ + + +# 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: + +* the Docker Gitter IM + room +* the docker-dev Google group +* the `#docker-dev` channel on Freenode IRC diff --git a/docs/ways/index.md b/docs/ways/index.md new file mode 100644 index 0000000000..de69e1ee5c --- /dev/null +++ b/docs/ways/index.md @@ -0,0 +1,17 @@ + + +# Ways to contribute + +* [Support the community](community.md) +* [Organize our Issues](issues.md) +* [Organize a Docker Meetup](meetups.md) +* [Test contributions](test.md) diff --git a/docs/ways/issues.md b/docs/ways/issues.md new file mode 100644 index 0000000000..ced07eb498 --- /dev/null +++ b/docs/ways/issues.md @@ -0,0 +1,92 @@ + + +# 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. + +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: + + + + + + + + + + + + + + + + + + + + + + + + +
docker/dockerDocker the open-source application container engine
docker/machineSoftware for the easy and quick creation of Docker hosts on your computer, on cloud providers, and inside your own data center.
kitematic/kitematicKitematic is a simple application for managing Docker containers on Mac OS X and Windows.
docker/swarmNative clustering for Docker; manage several Docker hosts as a single, virtual host.
docker/composeDefine and run complex applications using one or many interlinked containers.
+ + +See the complete list of +Docker repositories on GitHub. + +3. Choose an issue from the list of untriaged issues. + +4. Follow the the triage process 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 the triage process + +5. Triage another issue. diff --git a/docs/ways/meetups.md b/docs/ways/meetups.md new file mode 100644 index 0000000000..f6646ac2e4 --- /dev/null +++ b/docs/ways/meetups.md @@ -0,0 +1,72 @@ + + +# Organize a Docker Meetup + +Anyone interested in Docker can become an active member of the Docker community +by becoming 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 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, DigitlOcean, 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/docs/ways/test.md b/docs/ways/test.md new file mode 100644 index 0000000000..ab11d132dd --- /dev/null +++ b/docs/ways/test.md @@ -0,0 +1,58 @@ + + +# 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 +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 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: + +## Step 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 is something anyone with Docker can do. While changing +volume directories in Kitematic requires a Mac and Docker's Kitematic +installed. + +## Step 2. Try and follow the procedure or recreate the example. + +What to 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? + +## Step 3. If you couldn't complete the procedure or example, file an issue in the Docker repo. + +# Test code in the 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/docs/workflow/advanced-contributing.md b/docs/workflow/advanced-contributing.md new file mode 100644 index 0000000000..8441315f51 --- /dev/null +++ b/docs/workflow/advanced-contributing.md @@ -0,0 +1,159 @@ + + +# 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. + +## 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. + +3. Talk to the community about your idea. + + We have lots of community forums + 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/docs/workflow/coding-style.md b/docs/workflow/coding-style.md new file mode 100644 index 0000000000..8440321354 --- /dev/null +++ b/docs/workflow/coding-style.md @@ -0,0 +1,103 @@ + + +# 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 them 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. + +* If you made a documentation change, you can see it at + [docs.master.dockerproject.org](http://docs.master.dockerproject.org/). diff --git a/docs/workflow/create-pr.md b/docs/workflow/create-pr.md new file mode 100644 index 0000000000..8ab94b0a30 --- /dev/null +++ b/docs/workflow/create-pr.md @@ -0,0 +1,139 @@ + + +# 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. Optionally, if modified the documentation, build the documentation: + + $ make docs + +5. 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/docs/workflow/find-an-issue.md b/docs/workflow/find-an-issue.md new file mode 100644 index 0000000000..40302ae7df --- /dev/null +++ b/docs/workflow/find-an-issue.md @@ -0,0 +1,299 @@ + + + + + + +# 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/bug + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
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/docker/docker.git (fetch) + upstream https://github.com/docker/docker.git (push) + + If the `upstream` is missing, add it. + + $ git remote add upstream https://github.com/docker/docker.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 + + This command says get all the changes from the `master` branch belonging to + the `upstream` remote. + +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/docs/workflow/images/commits_expected.png b/docs/workflow/images/commits_expected.png new file mode 100644 index 0000000000..d3d8b1e3cf Binary files /dev/null and b/docs/workflow/images/commits_expected.png differ diff --git a/docs/workflow/images/easy_issue.png b/docs/workflow/images/easy_issue.png new file mode 100644 index 0000000000..6d346bcd87 Binary files /dev/null and b/docs/workflow/images/easy_issue.png differ diff --git a/docs/workflow/images/existing_issue.png b/docs/workflow/images/existing_issue.png new file mode 100644 index 0000000000..6757e60bb7 Binary files /dev/null and b/docs/workflow/images/existing_issue.png differ diff --git a/docs/workflow/images/fixes_num.png b/docs/workflow/images/fixes_num.png new file mode 100644 index 0000000000..df52f27fd9 Binary files /dev/null and b/docs/workflow/images/fixes_num.png differ diff --git a/docs/workflow/images/gordon.jpeg b/docs/workflow/images/gordon.jpeg new file mode 100644 index 0000000000..8a0df7d463 Binary files /dev/null and b/docs/workflow/images/gordon.jpeg differ diff --git a/docs/workflow/images/issue_list.png b/docs/workflow/images/issue_list.png new file mode 100644 index 0000000000..0d954986bb Binary files /dev/null and b/docs/workflow/images/issue_list.png differ diff --git a/docs/workflow/images/latest_commits.png b/docs/workflow/images/latest_commits.png new file mode 100644 index 0000000000..791683a5c5 Binary files /dev/null and b/docs/workflow/images/latest_commits.png differ diff --git a/docs/workflow/images/locate_branch.png b/docs/workflow/images/locate_branch.png new file mode 100644 index 0000000000..b865cfcbf4 Binary files /dev/null and b/docs/workflow/images/locate_branch.png differ diff --git a/docs/workflow/images/proposal.png b/docs/workflow/images/proposal.png new file mode 100644 index 0000000000..250781a70d Binary files /dev/null and b/docs/workflow/images/proposal.png differ diff --git a/docs/workflow/images/pull_request_made.png b/docs/workflow/images/pull_request_made.png new file mode 100644 index 0000000000..d51a1a75fa Binary files /dev/null and b/docs/workflow/images/pull_request_made.png differ diff --git a/docs/workflow/images/to_from_pr.png b/docs/workflow/images/to_from_pr.png new file mode 100644 index 0000000000..8dd6638e1b Binary files /dev/null and b/docs/workflow/images/to_from_pr.png differ diff --git a/docs/workflow/index.md b/docs/workflow/index.md new file mode 100644 index 0000000000..9f1f0bc335 --- /dev/null +++ b/docs/workflow/index.md @@ -0,0 +1,20 @@ + + +# 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) diff --git a/docs/workflow/make-a-contribution.md b/docs/workflow/make-a-contribution.md new file mode 100644 index 0000000000..ce2f2d987e --- /dev/null +++ b/docs/workflow/make-a-contribution.md @@ -0,0 +1,41 @@ + + +# 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). diff --git a/docs/workflow/review-pr.md b/docs/workflow/review-pr.md new file mode 100644 index 0000000000..d699d9692e --- /dev/null +++ b/docs/workflow/review-pr.md @@ -0,0 +1,141 @@ + + + +# 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. + + +## 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, the "beings" review your work. Docker maintainers look +at your pull request and comment on it. The shortest comment you might see is +`LGTM` which means **l**ooks-**g**ood-**t**o-**m**e. 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. All maintainer comments on a PR go to the +email address associated with your GitHub account. Any GitHub user who +"participates" in a PR receives an email to. Participating means creating or +commenting on a PR. + +Our maintainers are very experienced Docker users and open source contributors. +So, 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 `docker-fork` repository. + + This is the branch associated with your request. + +2. Change one or more files and then stage your changes. + + The command syntax is: + + git add + +3. Commit the change. + + $ git commit --amend + + Git opens an editor containing your last commit message. + +4. Adjust your last comment to reflect this new change. + + 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. + + The command syntax is: + + 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/. + +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. + +4. View any documentation changes at docs.master.dockerproject.org. + +Once you've verified everything merged, feel free to delete your feature branch +from your fork. For information on how to do this, + +see the GitHub help on deleting branches. + +## 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/docs/workflow/work-issue.md b/docs/workflow/work-issue.md new file mode 100644 index 0000000000..78c9bbce96 --- /dev/null +++ b/docs/workflow/work-issue.md @@ -0,0 +1,200 @@ + + + +# Work on your issue + +The work you do for your issue 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 you 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). diff --git a/maintainercollector/generate.go b/maintainercollector/generate.go new file mode 100644 index 0000000000..64297522d1 --- /dev/null +++ b/maintainercollector/generate.go @@ -0,0 +1,43 @@ +// +build ignore + +package main + +import ( + "fmt" + "io/ioutil" + "os" + "path/filepath" +) + +func main() { + wd, err := os.Getwd() + if err != nil { + panic(err) + } + + if err := generateFile(wd, "rules.toml", "rules"); err != nil { + panic(err) + } + + if err := generateFile(wd, "roles.toml", "roles"); err != nil { + panic(err) + } +} + +func generateFile(wd string, file string, target string) error { + src, err := ioutil.ReadFile(file) + if err != nil { + panic(err) + } + out, err := os.Create(filepath.Join(wd, target+".go")) + if err != nil { + return err + } + out.Write([]byte("// This file is autogenerated; DO NOT EDIT DIRECTLY\n// See maintainercollector/generate.go for more info\npackage main\n\nconst (\n")) + + out.Write([]byte(fmt.Sprintf("%s = %q", target, string(src)))) + + out.Write([]byte("\n)\n")) + + return nil +} diff --git a/maintainercollector/main.go b/maintainercollector/main.go new file mode 100644 index 0000000000..6f2163df6e --- /dev/null +++ b/maintainercollector/main.go @@ -0,0 +1,174 @@ +package main + +import ( + "bytes" + "fmt" + "io/ioutil" + "net/http" + "strings" + + "github.com/BurntSushi/toml" + "github.com/Sirupsen/logrus" +) + +const ( + ghRawUri = "https://raw.githubusercontent.com" + head = `# +# THIS FILE IS AUTOGENERATED; SEE "./maintainercollector"! +# +# Docker projects maintainers file +# +# This file describes who runs the Docker project and how. +# This is a living document - if you see something out of date or missing, +# speak up! +# +# It is structured to be consumable by both humans and programs. +# To extract its contents programmatically, use any TOML-compliant +# parser. +` +) + +var ( + org = "docker" + projects = []string{ + "boot2docker", + "compose", + "containerd", + "datakit", + "distribution", + "docker", + "docker-bench-security", + "docker-credential-helpers", + "docker-py", + "dockercraft", + "engine-api", + "go-connections", + "go-events", + "go-p9p", + "go-plugins-helpers", + "go-units", + "hyperkit", + "kitematic", + "leadership", + "leeroy", + "libchan", + "libcompose", + "libkv", + "libnetwork", + "machine", + "migrator", + "notary", + "spdystream", + "swarm", + "swarmkit", + "swarm-frontends", + "toolbox", + "v1.10-migrator", + "vpnkit", + } +) + +//go:generate go run generate.go + +func main() { + // initialize the project MAINTAINERS file + projectMaintainers := Maintainers{ + Org: map[string]*Org{}, + People: map[string]Person{}, + } + + // initialize Curators + projectMaintainers.Org["Curators"] = &Org{} + projectMaintainers.Org["Docs maintainers"] = &Org{} + + // parse the MAINTAINERS file for each repo + for _, project := range projects { + maintainers, err := getMaintainers(project) + if err != nil { + logrus.Errorf("%s: parsing MAINTAINERS file failed: %v", project, err) + continue + } + + // create the Org object for the project + p := &Org{ + // Repo: fmt.Sprintf("https://github.com/%s/%s", org, project), + // TODO: change this to: + // People: maintainers.Org["Core maintainers"].People, + // once MaintainersDepreciated is removed. + People: maintainers.Organization.CoreMaintainers.People, + } + + // lowercase all maintainers nicks for consistency + for i, n := range p.People { + p.People[i] = strings.ToLower(n) + } + + projectMaintainers.Org[project] = p + + if maintainers.Organization.DocsMaintainers != nil { + projectMaintainers.Org["Docs maintainers"].People = append(projectMaintainers.Org["Docs maintainers"].People, maintainers.Organization.DocsMaintainers.People...) + } + + if maintainers.Organization.Curators != nil { + projectMaintainers.Org["Curators"].People = append(projectMaintainers.Org["Curators"].People, maintainers.Organization.Curators.People...) + } + + // iterate through the people and add them to compiled list + for nick, person := range maintainers.People { + projectMaintainers.People[strings.ToLower(nick)] = person + } + } + + projectMaintainers.Org["Curators"].People = removeDuplicates(projectMaintainers.Org["Curators"].People) + projectMaintainers.Org["Docs maintainers"].People = removeDuplicates(projectMaintainers.Org["Docs maintainers"].People) + + // encode the result to a file + buf := new(bytes.Buffer) + t := toml.NewEncoder(buf) + t.Indent = " " + if err := t.Encode(projectMaintainers); err != nil { + logrus.Fatalf("TOML encoding error: %v", err) + } + + file := append([]byte(head), []byte(rules)...) + file = append(file, []byte(roles)...) + file = append(file, buf.Bytes()...) + + if err := ioutil.WriteFile("MAINTAINERS", file, 0755); err != nil { + logrus.Fatal(err) + } + + logrus.Infof("Successfully wrote new combined MAINTAINERS file.") +} + +func removeDuplicates(slice []string) []string { + seens := map[string]bool{} + uniqs := []string{} + for _, element := range slice { + if _, seen := seens[element]; !seen { + uniqs = append(uniqs, element) + seens[element] = true + } + } + return uniqs +} + +func getMaintainers(project string) (maintainers MaintainersDepreciated, err error) { + fileUrl := fmt.Sprintf("%s/%s/%s/master/MAINTAINERS", ghRawUri, org, project) + resp, err := http.Get(fileUrl) + if err != nil { + return maintainers, fmt.Errorf("%s: %v", project, err) + } + defer resp.Body.Close() + + file, err := ioutil.ReadAll(resp.Body) + if err != nil { + return maintainers, fmt.Errorf("%s: %v", project, err) + } + + if _, err := toml.Decode(string(file), &maintainers); err != nil { + return maintainers, fmt.Errorf("%s: parsing MAINTAINERS file failed: %v", project, err) + } + + return maintainers, nil +} diff --git a/maintainercollector/roles.toml b/maintainercollector/roles.toml new file mode 100644 index 0000000000..b4e02026e4 --- /dev/null +++ b/maintainercollector/roles.toml @@ -0,0 +1,48 @@ +# Current project roles +[Roles] + + [Roles.bdfl] + + person = "shykes" + + [Roles."Chief Architect"] + + person = "shykes" + + text = """ +The chief architect is responsible for the overall integrity of the technical architecture +across all subsystems, and the consistency of APIs and UI. + +Changes to UI, public APIs and overall architecture (for example a plugin system) must +be approved by the chief architect. +""" + + [Roles."Chief Maintainer"] + + person = "crosbymichael" + + text = """ +The chief maintainer is responsible for all aspects of quality for the project including +code reviews, usability, stability, security, performance, etc. +The most important function of the chief maintainer is to lead by example. On the first +day of a new maintainer, the best advice should be "follow the C.M.'s example and you'll +be fine". +""" + + [Roles."Community Manager"] + + person = "theadactyl" + + text = """ +The community manager is responsible for serving the project community, including users, +contributors and partners. This involves: + - facilitating communication between maintainers, contributors and users + - organizing contributor and maintainer events + - helping new contributors get involved + - anything the project community needs to be successful + +The community manager is a point of contact for any contributor who has questions, concerns +or feedback about project operations. +""" + + diff --git a/maintainercollector/rules.toml b/maintainercollector/rules.toml new file mode 100644 index 0000000000..edf0dc3f2e --- /dev/null +++ b/maintainercollector/rules.toml @@ -0,0 +1,240 @@ +[Rules] + + [Rules.maintainers] + + title = "What is a maintainer?" + + text = """ +There are different types of maintainers, with different responsibilities, but +all maintainers have 3 things in common: + +1) They share responsibility in the project's success. +2) They have made a long-term, recurring time investment to improve the project. +3) They spend that time doing whatever needs to be done, not necessarily what +is the most interesting or fun. + +Maintainers are often under-appreciated, because their work is harder to appreciate. +It's easy to appreciate a really cool and technically advanced feature. It's harder +to appreciate the absence of bugs, the slow but steady improvement in stability, +or the reliability of a release process. But those things distinguish a good +project from a great one. +""" + [Rules.adding-maintainers] + + title = "How are maintainers added?" + + text = """ +Maintainers are first and foremost contributors that have shown they are +committed to the long term success of a project. Contributors wanting to +become maintainers are expected to be deeply involved in contributing code, +pull request review, and triage of issues in the project for more than three +months. + +Just contributing does not make you a maintainer, it is about building trust +with the current maintainers of the project and being a person that they can +depend on and trust to make decisions in the best interest of the project. + +Maintainers are assigned per project (repository). Being a maintainer in +one project does not automatically make you a maintainer in other projects. + +Periodically, the existing maintainers curate a list of contributors that have +shown regular activity on the project over the prior months. From this +list, maintainer candidates are selected and proposed on the maintainers +mailing list. + +After a candidate has been announced on the maintainers mailing list, the +existing maintainers are given five business days to discuss the candidate, +raise objections and cast their vote. Candidates must be approved by the BDFL +and at least 66% of the current maintainers by adding their vote on the mailing +list. Only maintainers of the repository that the candidate is proposed for are +allowed to vote. The BDFL's vote is mandatory. + +If a candidate is approved, a maintainer will contact the candidate to +invite the candidate to open a pull request that adds the contributor to +the MAINTAINERS file. The candidate becomes a maintainer once the pull +request is merged. +""" + + [Rules.stepping-down-policy] + + title = "Stepping down policy" + + text = """ +Life priorities, interests, and passions can change. If you're a maintainer but +feel you must remove yourself from the list, inform other maintainers that you +intend to step down, and if possible, help find someone to pick up your work. +At the very least, ensure your work can be continued where you left off. + +After you've informed other maintainers, create a pull request to remove +yourself from the MAINTAINERS file. +""" + + [Rules.inactive-maintainers] + + title = "Removal of inactive maintainers" + + text = """ +Similar to the procedure for adding new maintainers, existing maintainers can +be removed from the list if they do not show significant activity on the +project. Periodically, the maintainers review the list of maintainers and their +activity over the last three months. + +If a maintainer has shown insufficient activity over this period, a neutral +person will contact the maintainer to ask if they want to continue being +a maintainer. If the maintainer decides to step down as a maintainer, they +open a pull request to be removed from the MAINTAINERS file. + +If the maintainer wants to remain a maintainer, but is unable to perform the +required duties they can be removed with a vote by the BDFL and at least 66% of +the current maintainers. The BDFL's vote is mandatory. An e-mail is sent to the +mailing list, inviting maintainers of the project to vote. The voting period is +five business days. Issues related to a maintainer's performance should be +discussed with them among the other maintainers so that they are not surprised +by a pull request removing them. +""" + + [Rules.alumni] + + title = "Alumni" + + text = """ +Projects can opt to keep a list of former maintainers in the MAINTAINERS file. +Instead of removing a maintainer from the file when they step down, the maintainer +is moved to the alumni list (`[Org.Alumni]`). People on this list have +no official capacity in the project, it's a way to say "thank you" for the +work they have done for the project. +""" + + [Rules.bdfl] + + title = "The Benevolent dictator for life (BDFL)" + + text = """ +Docker follows the timeless, highly efficient and totally unfair system +known as [Benevolent dictator for +life](https://en.wikipedia.org/wiki/Benevolent_Dictator_for_Life), with +yours truly, Solomon Hykes, in the role of BDFL. This means that all +decisions are made, by default, by Solomon. Since making every decision +myself would be highly un-scalable, in practice decisions are spread +across multiple maintainers. + +Ideally, the BDFL role is like the Queen of England: awesome crown, but not +an actual operational role day-to-day. The real job of a BDFL is to NEVER GO AWAY. +Every other rule can change, perhaps drastically so, but the BDFL will always +be there, preserving the philosophy and principles of the project, and keeping +ultimate authority over its fate. This gives us great flexibility in experimenting +with various governance models, knowing that we can always press the "reset" button +without fear of fragmentation or deadlock. See the US congress for a counter-example. + +BDFL daily routine: + +* Is the project governance stuck in a deadlock or irreversibly fragmented? + * If yes: refactor the project governance +* Are there issues or conflicts escalated by core? + * If yes: resolve them +* Go back to polishing that crown. +""" + + [Rules.decisions] + + title = "How are decisions made?" + + text = """ +Short answer: EVERYTHING IS A PULL REQUEST. + +Docker is an open-source project with an open design philosophy. This +means that the repository is the source of truth for EVERY aspect of the +project, including its philosophy, design, road map, and APIs. *If it's +part of the project, it's in the repo. If it's in the repo, it's part of +the project.* + +As a result, all decisions can be expressed as changes to the +repository. An implementation change is a change to the source code. An +API change is a change to the API specification. A philosophy change is +a change to the philosophy manifesto, and so on. + +All decisions affecting Docker, big and small, follow the same 3 steps: + +* Step 1: Open a pull request. Anyone can do this. + +* Step 2: Discuss the pull request. Anyone can do this. + +* Step 3: Merge or refuse the pull request. Who does this depends on the nature +of the pull request and which areas of the project it affects. See *review flow* +for details. + +Because Docker is such a large and active project, it's important for everyone to know +who is responsible for deciding what. That is determined by a precise set of rules. + +* For every *decision* in the project, the rules should designate, in a deterministic way, +who should *decide*. + +* For every *problem* in the project, the rules should designate, in a deterministic way, +who should be responsible for *fixing* it. + +* For every *question* in the project, the rules should designate, in a deterministic way, +who should be expected to have the *answer*. +""" + + [Rules.review] + + title = "Review flow" + + text = """ +Pull requests should be processed according to the following flow: + +* For each subsystem affected by the change, the maintainers of the subsystem must approve or refuse it. +It is the responsibility of the subsystem maintainers to process patches affecting them in a timely +manner. + +* If the change affects areas of the code which are not part of a subsystem, +or if subsystem maintainers are unable to reach a timely decision, it must be approved by +the core maintainers. + +* If the change affects the UI or public APIs, or if it represents a major change in architecture, +the architects must approve or refuse it. + +* If the change affects the operations of the project, it must be approved or rejected by +the relevant operators. + +* If the change affects the governance, philosophy, goals or principles of the project, +it must be approved by BDFL. +""" + + [Rules.DCO] + + title = "Helping contributors with the DCO" + + text = """ +The [DCO or `Sign your work`]( +https://github.com/docker/docker/blob/master/CONTRIBUTING.md#sign-your-work) +requirement is not intended as a roadblock or speed bump. + +Some Docker contributors are not as familiar with `git`, or have used a web based +editor, and thus asking them to `git commit --amend -s` is not the best way forward. + +In this case, maintainers can update the commits based on clause (c) of the DCO. The +most trivial way for a contributor to allow the maintainer to do this, is to add +a DCO signature in a pull requests's comment, or a maintainer can simply note that +the change is sufficiently trivial that it does not substantially change the existing +contribution - i.e., a spelling change. + +When you add someone's DCO, please also add your own to keep a log. +""" + + [Rules."no direct push"] + + title = "I'm a maintainer. Should I make pull requests too?" + + text = """ +Yes. Nobody should ever push to master directly. All changes should be +made through a pull request. +""" + + [Rules.meta] + + title = "How is this process changed?" + + text = "Just like everything else: by making a pull request :)" + + diff --git a/maintainercollector/types.go b/maintainercollector/types.go new file mode 100644 index 0000000000..ec56a9780a --- /dev/null +++ b/maintainercollector/types.go @@ -0,0 +1,54 @@ +package main + +// Maintainers defines the struct for a MAINTAINERS file +type Maintainers struct { + Rules map[string]Rule + Roles map[string]Role + Org map[string]*Org + People map[string]Person +} + +// Rule is a project rule +type Rule struct { + Title string `toml:"title,omitempty"` + Text string `toml:"text,omitempty"` +} + +// Role is a project role +type Role struct { + Person string `toml:"person,omitempty"` + Text string `toml:"text,omitempty"` +} + +// Org defines the organization within a project +type Org struct { + People []string +} + +// Person member of the project +type Person struct { + Name string + Email string + GitHub string +} + +// MaintainersDepreciated is an old struct for compatibility +// with the docker/docker maintainers file. +// TODO: delete this once the file in docker/docker repo is updated +type MaintainersDepreciated struct { + Rules map[string]Rule + Organization Organization `toml:"Org"` + People map[string]Person +} + +// Organization defines the project's organization +// TODO: delete this once MaintainersDepreciated is removed +type Organization struct { + BDFL string `toml:"bdfl"` + ChiefArchitect string `toml:"Chief Architect"` + ChiefMaintainer string `toml:"Chief Maintainer"` + CommunityManager string `toml:"Community Manager"` + CoreMaintainers *Org `toml:"Core maintainers"` + DocsMaintainers *Org `toml:"Docs maintainers"` + Curators *Org `toml:"Curators"` +} diff --git a/project-template/CONTRIBUTING.md b/project-template/CONTRIBUTING.md new file mode 100644 index 0000000000..4d99e17b99 --- /dev/null +++ b/project-template/CONTRIBUTING.md @@ -0,0 +1,70 @@ +# Contributing to Docker open source projects + +Want to hack on this project? Awesome! Here are instructions to get you started. + +This project is a part of the [Docker](https://www.docker.com) project, and follows +the same rules and principles. If you're already familiar with the way +Docker does things, you'll feel right at home. + +Otherwise, go read Docker's +[contributions guidelines](https://github.com/docker/docker/blob/master/CONTRIBUTING.md), +[issue triaging](https://github.com/docker/docker/blob/master/project/ISSUE-TRIAGE.md), +[review process](https://github.com/docker/docker/blob/master/project/REVIEWING.md) and +[branches and tags](https://github.com/docker/docker/blob/master/project/BRANCHES-AND-TAGS.md). + +For an in-depth description of our contribution process, visit the +contributors guide: [Understand how to contribute](https://docs.docker.com/opensource/workflow/make-a-contribution/) + +### Sign your work + +The sign-off is a simple line at the end of the explanation for the patch. Your +signature certifies that you wrote the patch or otherwise have the right to pass +it on as an open-source patch. The rules are pretty simple: if you can certify +the below (from [developercertificate.org](http://developercertificate.org/)): + +``` +Developer Certificate of Origin +Version 1.1 + +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. +660 York Street, Suite 102, +San Francisco, CA 94110 USA + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + +Developer's Certificate of Origin 1.1 + +By making a contribution to this project, I certify that: + +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +(c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. +``` + +Then you just add a line to every git commit message: + + Signed-off-by: Joe Smith + +Use your real name (sorry, no pseudonyms or anonymous contributions.) + +If you set your `user.name` and `user.email` git configs, you can sign your +commit automatically with `git commit -s`. diff --git a/project-template/INSTRUCTIONS.md b/project-template/INSTRUCTIONS.md new file mode 100644 index 0000000000..3881dbba37 --- /dev/null +++ b/project-template/INSTRUCTIONS.md @@ -0,0 +1,29 @@ +# Docker open source project template + +This directory contains a template for setting up a new open source +project. + +## Checklist + +- [ ] Update the "Project name" and description of your project in the README.md. +- [ ] Add details of the project's maintainers to the MAINTAINERS file. +- [ ] Setup DCO checks with "leeroy". Instructions can be found [in the README](https://github.com/docker/leeroy). +- [ ] Request the maintainers to be added to the maintainers mailinglist. +- [ ] Request the maintainers to be "voiced" in the #docker-maintainers IRC channel. +- [ ] Add the standard "labels" for triaging issues, as described in [REVIEWING.md](https://github.com/docker/docker/blob/master/project/REVIEWING.md) + and [ISSUE-TRIAGE.md](https://github.com/docker/docker/blob/master/project/ISSUE-TRIAGE.md) + + +### After the repository is public + +If you're project is ready to go public: + +- [ ] Create a pull request to have the project added to the central + MAINTAINERS file in the docker/opensource repository. Make sure + to run `make maintainers` to update the MAINTAINERS file with your + changes. An example pull request can be found here; https://github.com/docker/opensource/pull/45 +- [ ] Remove this file from the repository :) +- [ ] Spread the word! + + +Congratulations, you're done! diff --git a/project-template/LICENSE.code b/project-template/LICENSE.code new file mode 100644 index 0000000000..b55b37bc31 --- /dev/null +++ b/project-template/LICENSE.code @@ -0,0 +1,191 @@ + + Apache License + Version 2.0, January 2004 + https://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + Copyright 2015 Docker, Inc. + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + https://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/project-template/LICENSE.docs b/project-template/LICENSE.docs new file mode 100644 index 0000000000..e26cd4fc8e --- /dev/null +++ b/project-template/LICENSE.docs @@ -0,0 +1,425 @@ +Attribution-ShareAlike 4.0 International + +======================================================================= + +Creative Commons Corporation ("Creative Commons") is not a law firm and +does not provide legal services or legal advice. Distribution of +Creative Commons public licenses does not create a lawyer-client or +other relationship. Creative Commons makes its licenses and related +information available on an "as-is" basis. Creative Commons gives no +warranties regarding its licenses, any material licensed under their +terms and conditions, or any related information. Creative Commons +disclaims all liability for damages resulting from their use to the +fullest extent possible. + +Using Creative Commons Public Licenses + +Creative Commons public licenses provide a standard set of terms and +conditions that creators and other rights holders may use to share +original works of authorship and other material subject to copyright +and certain other rights specified in the public license below. The +following considerations are for informational purposes only, are not +exhaustive, and do not form part of our licenses. + + Considerations for licensors: Our public licenses are + intended for use by those authorized to give the public + permission to use material in ways otherwise restricted by + copyright and certain other rights. Our licenses are + irrevocable. Licensors should read and understand the terms + and conditions of the license they choose before applying it. + Licensors should also secure all rights necessary before + applying our licenses so that the public can reuse the + material as expected. Licensors should clearly mark any + material not subject to the license. This includes other CC- + licensed material, or material used under an exception or + limitation to copyright. More considerations for licensors: + wiki.creativecommons.org/Considerations_for_licensors + + Considerations for the public: By using one of our public + licenses, a licensor grants the public permission to use the + licensed material under specified terms and conditions. If + the licensor's permission is not necessary for any reason--for + example, because of any applicable exception or limitation to + copyright--then that use is not regulated by the license. Our + licenses grant only permissions under copyright and certain + other rights that a licensor has authority to grant. Use of + the licensed material may still be restricted for other + reasons, including because others have copyright or other + rights in the material. A licensor may make special requests, + such as asking that all changes be marked or described. + Although not required by our licenses, you are encouraged to + respect those requests where reasonable. More_considerations + for the public: + wiki.creativecommons.org/Considerations_for_licensees + +======================================================================= + +Creative Commons Attribution-ShareAlike 4.0 International Public +License + +By exercising the Licensed Rights (defined below), You accept and agree +to be bound by the terms and conditions of this Creative Commons +Attribution-ShareAlike 4.0 International Public License ("Public +License"). To the extent this Public License may be interpreted as a +contract, You are granted the Licensed Rights in consideration of Your +acceptance of these terms and conditions, and the Licensor grants You +such rights in consideration of benefits the Licensor receives from +making the Licensed Material available under these terms and +conditions. + + +Section 1 -- Definitions. + + a. Adapted Material means material subject to Copyright and Similar + Rights that is derived from or based upon the Licensed Material + and in which the Licensed Material is translated, altered, + arranged, transformed, or otherwise modified in a manner requiring + permission under the Copyright and Similar Rights held by the + Licensor. For purposes of this Public License, where the Licensed + Material is a musical work, performance, or sound recording, + Adapted Material is always produced where the Licensed Material is + synched in timed relation with a moving image. + + b. Adapter's License means the license You apply to Your Copyright + and Similar Rights in Your contributions to Adapted Material in + accordance with the terms and conditions of this Public License. + + c. BY-SA Compatible License means a license listed at + creativecommons.org/compatiblelicenses, approved by Creative + Commons as essentially the equivalent of this Public License. + + d. Copyright and Similar Rights means copyright and/or similar rights + closely related to copyright including, without limitation, + performance, broadcast, sound recording, and Sui Generis Database + Rights, without regard to how the rights are labeled or + categorized. For purposes of this Public License, the rights + specified in Section 2(b)(1)-(2) are not Copyright and Similar + Rights. + + e. Effective Technological Measures means those measures that, in the + absence of proper authority, may not be circumvented under laws + fulfilling obligations under Article 11 of the WIPO Copyright + Treaty adopted on December 20, 1996, and/or similar international + agreements. + + f. Exceptions and Limitations means fair use, fair dealing, and/or + any other exception or limitation to Copyright and Similar Rights + that applies to Your use of the Licensed Material. + + g. License Elements means the license attributes listed in the name + of a Creative Commons Public License. The License Elements of this + Public License are Attribution and ShareAlike. + + h. Licensed Material means the artistic or literary work, database, + or other material to which the Licensor applied this Public + License. + + i. Licensed Rights means the rights granted to You subject to the + terms and conditions of this Public License, which are limited to + all Copyright and Similar Rights that apply to Your use of the + Licensed Material and that the Licensor has authority to license. + + j. Licensor means the individual(s) or entity(ies) granting rights + under this Public License. + + k. Share means to provide material to the public by any means or + process that requires permission under the Licensed Rights, such + as reproduction, public display, public performance, distribution, + dissemination, communication, or importation, and to make material + available to the public including in ways that members of the + public may access the material from a place and at a time + individually chosen by them. + + l. Sui Generis Database Rights means rights other than copyright + resulting from Directive 96/9/EC of the European Parliament and of + the Council of 11 March 1996 on the legal protection of databases, + as amended and/or succeeded, as well as other essentially + equivalent rights anywhere in the world. + + m. You means the individual or entity exercising the Licensed Rights + under this Public License. Your has a corresponding meaning. + + +Section 2 -- Scope. + + a. License grant. + + 1. Subject to the terms and conditions of this Public License, + the Licensor hereby grants You a worldwide, royalty-free, + non-sublicensable, non-exclusive, irrevocable license to + exercise the Licensed Rights in the Licensed Material to: + + a. reproduce and Share the Licensed Material, in whole or + in part; and + + b. produce, reproduce, and Share Adapted Material. + + 2. Exceptions and Limitations. For the avoidance of doubt, where + Exceptions and Limitations apply to Your use, this Public + License does not apply, and You do not need to comply with + its terms and conditions. + + 3. Term. The term of this Public License is specified in Section + 6(a). + + 4. Media and formats; technical modifications allowed. The + Licensor authorizes You to exercise the Licensed Rights in + all media and formats whether now known or hereafter created, + and to make technical modifications necessary to do so. The + Licensor waives and/or agrees not to assert any right or + authority to forbid You from making technical modifications + necessary to exercise the Licensed Rights, including + technical modifications necessary to circumvent Effective + Technological Measures. For purposes of this Public License, + simply making modifications authorized by this Section 2(a) + (4) never produces Adapted Material. + + 5. Downstream recipients. + + a. Offer from the Licensor -- Licensed Material. Every + recipient of the Licensed Material automatically + receives an offer from the Licensor to exercise the + Licensed Rights under the terms and conditions of this + Public License. + + b. Additional offer from the Licensor -- Adapted Material. + Every recipient of Adapted Material from You + automatically receives an offer from the Licensor to + exercise the Licensed Rights in the Adapted Material + under the conditions of the Adapter's License You apply. + + c. No downstream restrictions. You may not offer or impose + any additional or different terms or conditions on, or + apply any Effective Technological Measures to, the + Licensed Material if doing so restricts exercise of the + Licensed Rights by any recipient of the Licensed + Material. + + 6. No endorsement. Nothing in this Public License constitutes or + may be construed as permission to assert or imply that You + are, or that Your use of the Licensed Material is, connected + with, or sponsored, endorsed, or granted official status by, + the Licensor or others designated to receive attribution as + provided in Section 3(a)(1)(A)(i). + + b. Other rights. + + 1. Moral rights, such as the right of integrity, are not + licensed under this Public License, nor are publicity, + privacy, and/or other similar personality rights; however, to + the extent possible, the Licensor waives and/or agrees not to + assert any such rights held by the Licensor to the limited + extent necessary to allow You to exercise the Licensed + Rights, but not otherwise. + + 2. Patent and trademark rights are not licensed under this + Public License. + + 3. To the extent possible, the Licensor waives any right to + collect royalties from You for the exercise of the Licensed + Rights, whether directly or through a collecting society + under any voluntary or waivable statutory or compulsory + licensing scheme. In all other cases the Licensor expressly + reserves any right to collect such royalties. + + +Section 3 -- License Conditions. + +Your exercise of the Licensed Rights is expressly made subject to the +following conditions. + + a. Attribution. + + 1. If You Share the Licensed Material (including in modified + form), You must: + + a. retain the following if it is supplied by the Licensor + with the Licensed Material: + + i. identification of the creator(s) of the Licensed + Material and any others designated to receive + attribution, in any reasonable manner requested by + the Licensor (including by pseudonym if + designated); + + ii. a copyright notice; + + iii. a notice that refers to this Public License; + + iv. a notice that refers to the disclaimer of + warranties; + + v. a URI or hyperlink to the Licensed Material to the + extent reasonably practicable; + + b. indicate if You modified the Licensed Material and + retain an indication of any previous modifications; and + + c. indicate the Licensed Material is licensed under this + Public License, and include the text of, or the URI or + hyperlink to, this Public License. + + 2. You may satisfy the conditions in Section 3(a)(1) in any + reasonable manner based on the medium, means, and context in + which You Share the Licensed Material. For example, it may be + reasonable to satisfy the conditions by providing a URI or + hyperlink to a resource that includes the required + information. + + 3. If requested by the Licensor, You must remove any of the + information required by Section 3(a)(1)(A) to the extent + reasonably practicable. + + b. ShareAlike. + + In addition to the conditions in Section 3(a), if You Share + Adapted Material You produce, the following conditions also apply. + + 1. The Adapter's License You apply must be a Creative Commons + license with the same License Elements, this version or + later, or a BY-SA Compatible License. + + 2. You must include the text of, or the URI or hyperlink to, the + Adapter's License You apply. You may satisfy this condition + in any reasonable manner based on the medium, means, and + context in which You Share Adapted Material. + + 3. You may not offer or impose any additional or different terms + or conditions on, or apply any Effective Technological + Measures to, Adapted Material that restrict exercise of the + rights granted under the Adapter's License You apply. + + +Section 4 -- Sui Generis Database Rights. + +Where the Licensed Rights include Sui Generis Database Rights that +apply to Your use of the Licensed Material: + + a. for the avoidance of doubt, Section 2(a)(1) grants You the right + to extract, reuse, reproduce, and Share all or a substantial + portion of the contents of the database; + + b. if You include all or a substantial portion of the database + contents in a database in which You have Sui Generis Database + Rights, then the database in which You have Sui Generis Database + Rights (but not its individual contents) is Adapted Material, + + including for purposes of Section 3(b); and + c. You must comply with the conditions in Section 3(a) if You Share + all or a substantial portion of the contents of the database. + +For the avoidance of doubt, this Section 4 supplements and does not +replace Your obligations under this Public License where the Licensed +Rights include other Copyright and Similar Rights. + + +Section 5 -- Disclaimer of Warranties and Limitation of Liability. + + a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE + EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS + AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF + ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, + IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, + WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR + PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, + ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT + KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT + ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. + + b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE + TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, + NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, + INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, + COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR + USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN + ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR + DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR + IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. + + c. The disclaimer of warranties and limitation of liability provided + above shall be interpreted in a manner that, to the extent + possible, most closely approximates an absolute disclaimer and + waiver of all liability. + + +Section 6 -- Term and Termination. + + a. This Public License applies for the term of the Copyright and + Similar Rights licensed here. However, if You fail to comply with + this Public License, then Your rights under this Public License + terminate automatically. + + b. Where Your right to use the Licensed Material has terminated under + Section 6(a), it reinstates: + + 1. automatically as of the date the violation is cured, provided + it is cured within 30 days of Your discovery of the + violation; or + + 2. upon express reinstatement by the Licensor. + + For the avoidance of doubt, this Section 6(b) does not affect any + right the Licensor may have to seek remedies for Your violations + of this Public License. + + c. For the avoidance of doubt, the Licensor may also offer the + Licensed Material under separate terms or conditions or stop + distributing the Licensed Material at any time; however, doing so + will not terminate this Public License. + + d. Sections 1, 5, 6, 7, and 8 survive termination of this Public + License. + + +Section 7 -- Other Terms and Conditions. + + a. The Licensor shall not be bound by any additional or different + terms or conditions communicated by You unless expressly agreed. + + b. Any arrangements, understandings, or agreements regarding the + Licensed Material not stated herein are separate from and + independent of the terms and conditions of this Public License. + + +Section 8 -- Interpretation. + + a. For the avoidance of doubt, this Public License does not, and + shall not be interpreted to, reduce, limit, restrict, or impose + conditions on any use of the Licensed Material that could lawfully + be made without permission under this Public License. + + b. To the extent possible, if any provision of this Public License is + deemed unenforceable, it shall be automatically reformed to the + minimum extent necessary to make it enforceable. If the provision + cannot be reformed, it shall be severed from this Public License + without affecting the enforceability of the remaining terms and + conditions. + + c. No term or condition of this Public License will be waived and no + failure to comply consented to unless expressly agreed to by the + Licensor. + + d. Nothing in this Public License constitutes or may be interpreted + as a limitation upon, or waiver of, any privileges and immunities + that apply to the Licensor or You, including from the legal + processes of any jurisdiction or authority. + + +======================================================================= + +Creative Commons is not a party to its public licenses. +Notwithstanding, Creative Commons may elect to apply one of its public +licenses to material it publishes and in those instances will be +considered the "Licensor." Except for the limited purpose of indicating +that material is shared under a Creative Commons public license or as +otherwise permitted by the Creative Commons policies published at +creativecommons.org/policies, Creative Commons does not authorize the +use of the trademark "Creative Commons" or any other trademark or logo +of Creative Commons without its prior written consent including, +without limitation, in connection with any unauthorized modifications +to any of its public licenses or any other arrangements, +understandings, or agreements concerning use of licensed material. For +the avoidance of doubt, this paragraph does not form part of the public +licenses. + +Creative Commons may be contacted at creativecommons.org. diff --git a/project-template/MAINTAINERS b/project-template/MAINTAINERS new file mode 100644 index 0000000000..e763b22fa9 --- /dev/null +++ b/project-template/MAINTAINERS @@ -0,0 +1,28 @@ +# Project maintainers file +# +# This file describes who runs the docker/PROJECT project and how. +# This is a living document - if you see something out of date or missing, speak up! +# +# It is structured to be consumable by both humans and programs. +# To extract its contents programmatically, use any TOML-compliant parser. +# +# This file is compiled into the MAINTAINERS file in docker/opensource. +# +[Org] + [Org."Core maintainers"] + people = [ + "MAINTAINER", + ] + +[people] + +# A reference list of all people associated with the project. +# All other sections should refer to people by their canonical key +# in the people section. + + # ADD YOURSELF HERE IN ALPHABETICAL ORDER + + [people.MAINTAINER] + Name = "NAME" + Email = "EMAIL" + GitHub = "MAINTAINER" diff --git a/project-template/README.md b/project-template/README.md new file mode 100644 index 0000000000..a913685f86 --- /dev/null +++ b/project-template/README.md @@ -0,0 +1,26 @@ +# Add your project name here + +Add a description here + +## Reporting security issues + +The maintainers take security seriously. If you discover a security issue, +please bring it to their attention right away! + +Please **DO NOT** file a public issue, instead send your report privately to +[security@docker.com](mailto:security@docker.com). + +Security reports are greatly appreciated and we will publicly thank you for it. +We also like to send gifts—if you're into Docker schwag, make sure to let +us know. We currently do not offer a paid security bounty program, but are not +ruling it out in the future. + + +## Copyright and license + +Copyright © 2015 Docker, Inc. All rights reserved, except as follows. Code +is released under the Apache 2.0 license. The README.md file, and files in the +"docs" folder are licensed under the Creative Commons Attribution 4.0 +International License under the terms and conditions set forth in the file +"LICENSE.docs". You may obtain a duplicate copy of the same license, titled +CC-BY-SA-4.0, at http://creativecommons.org/licenses/by/4.0/.