提交 18986c18 编写于 作者: T Thibaut

Going open source

上级
.DS_Store
.bundle
*.pxm
*.sketch
tmp
public/assets
public/fonts
public/docs/**/*
!public/docs/docs.json
!public/docs/**/index.json
# Contributing to DevDocs
Wish to contribute? Great. Please review the following guidelines carefully and always search for existing issues before opening a new one. More time spent managing issues means less time spent improving the software.
_Note: DevDocs is my first open source project and one which I deeply care about. Please forgive my inexperience and the fact that I may push back on certain things in order to keep the project to my liking. Feedback and advice are always welcome._
**Table of Contents:**
1. [Reporting bugs](#reporting-bugs)
2. [Requesting new features](#requesting-new-features)
3. [Requesting new docs](#requesting-new-docs)
4. [Contributing code and features](#contributing-code-and-features)
5. [Contributing new docs](#contributing-new-docs)
6. [Other contributions](#other-contributions)
7. [Coding conventions](#coding-conventions)
8. [Questions?](#questions)
## Reporting bugs
1. Always update to the most recent master release; the bug may already be fixed.
2. Search for existing issues; it's possible someone has already encountered this bug.
3. Try to isolate the problem and include steps to reproduce it.
4. Share as much information as possible (e.g. browser/OS environment, log output, stack trace, screenshots, etc.).
## Requesting new features
1. Search for similar feature requests; someone may have already requested it.
2. Make sure your feature fits DevDocs's [vision and stated goals](https://github.com/Thibaut/devdocs/blob/master/README.md#vision).
3. Provide a clear and detailed explanation of the feature and why it's important to add it.
For general feedback and ideas, please use the [mailing list](https://groups.google.com/d/forum/devdocs).
## Requesting new docs
Please do not open issues to request new documentations.
Use the [Trello board](https://trello.com/b/6BmTulfx/devdocs-documentation) where everyone can vote and contributors can get a feel for what's wished for.
## Contributing code and features
1. Search for existing issues; someone may already be working on a similar feature.
2. Before embarking on any significant pull request, please open an issue describing the changes you intend to make. Otherwise you risk spending a lot of time working on something that I may not want to merge. This also tells other contributors that you're working on the feature.
3. Follow the [coding conventions](#coding-conventions).
4. If you're modifying the Ruby code, include tests and ensure they pass.
5. Try to keep your pull request small and simple.
6. When it makes sense, squash your commits into a single commit.
7. Describe all your changes in the commit message and/or pull request.
## Contributing new docs
**Note:** there is currently no documentation on how to create a scraper/documentation. I'm working on it.
**Important:** in order to keep things fast and manageable, only the documentation of popular open source projects will be accepted into DevDocs. As more projects find their way in, the required level of popularity will gradually decrease. Additionally, the documentation's license must permit alteration, redistribution, and commercial use of the work. Software vendors that wish to add commercial software documentation to DevDocs may contact me privately.
**Please open an issue before adding any new documentation.**
In addition to the [guidelines for contributing code](#contributing-code-and-features), the following guidelines apply to pull requests that add a new documentation:
* Your documentation must come with a clean and official icon, in both 1x and 2x resolutions (16x16 and 32x32 pixels). This is important because icons are the only thing differentiating search results inside the app. If a project doesn't have an official icon, it won't be accepted into DevDocs—sorry.
* DevDocs favors quality over quantity. Your documentation should only include API/reference documents that most developers may wish to read semi-regularly. By reducing the number of entries you make it easier for people to find other, more relevant entries. _(Note: you're more than welcome to submit pull requests removing seldom-used entries from existing documentations.)_
* Try to remove as much content and HTML markup as possible, particularly content which isn't associated with any entries (e.g. introduction, changelog, etc.).
* Names must be as short as possible and unique across the documentation.
* The number of types (categories) must be less than 50.
* It's ok to leave the CSS up to me.
* Don't modify the icon sprite. I'll do it when merging your pull request.
* Once your documentation is accepted into DevDocs, you'll be expected to maintain it on a regular basis.
## Other contributions
Besides new docs and features, here are other ways you can contribute:
* **Improve words and sentences.** English isn't my first language so if you notice grammatical or usage errors, feel free to submit a pull request—it'll be much appreciated. (Note: American English is the preferred form)
* **Write documentation.** Although this task is mainly up to me, any documentation you can write that may help other developers understand and contribute to the code is highly appreciated.
* **Participate in the issue tracker.** Your opinion matters—feel free to add comments to existing issues. You're also welcome to participate to the [mailing list](https://groups.google.com/d/forum/devdocs).
## Coding conventions
* two spaces; no tabs
* no trailing whitespace; blank lines should have no spaces
* use the same coding style as the rest of the codebase
## Questions?
If you have any questions, please feel free to ask on the [mailing list](https://groups.google.com/d/forum/devdocs).
Copyright 2013 Thibaut Courouble and other contributors
This Source Code Form is subject to the terms of the Mozilla Public
License, v. 2.0. If a copy of the MPL was not distributed with this
file, You can obtain one at http://mozilla.org/MPL/2.0/.
NOTE: DevDocs is considered a trademark. You may not use the name to
endorse or promote products derived from this software without
Thibaut Courouble's permission, except as may be necessary to
comply with the notice/attribution requirements.
ADDITIONALLY: it is expected that any documentation file generated
using this software must be attributed to DevDocs. Let's be fair
to all contributors by not stealing their hard work.
source 'https://rubygems.org'
ruby '2.0.0'
gem 'thor'
gem 'pry', '~> 0.9.12'
gem 'activesupport', '~> 4.0', require: false
gem 'yajl-ruby', require: false
group :app do
gem 'rack'
gem 'sinatra'
gem 'sinatra-contrib'
gem 'thin'
gem 'sprockets'
gem 'sprockets-helpers'
gem 'erubis'
gem 'browser'
gem 'sass'
gem 'coffee-script'
end
group :production do
gem 'uglifier'
end
group :development do
gem 'better_errors'
end
group :docs do
gem 'typhoeus'
gem 'nokogiri', '~> 1.6.0'
gem 'html-pipeline'
gem 'progress_bar'
gem 'unix_utils'
end
group :test do
gem 'minitest'
gem 'rr', require: false
end
GEM
remote: https://rubygems.org/
specs:
activesupport (4.0.0)
i18n (~> 0.6, >= 0.6.4)
minitest (~> 4.2)
multi_json (~> 1.3)
thread_safe (~> 0.1)
tzinfo (~> 0.3.37)
atomic (1.1.14)
backports (3.3.5)
better_errors (1.0.1)
coderay (>= 1.0.0)
erubis (>= 2.6.6)
browser (0.2.1)
coderay (1.0.9)
coffee-script (2.2.0)
coffee-script-source
execjs
coffee-script-source (1.6.3)
daemons (1.1.9)
erubis (2.7.0)
escape_utils (0.3.2)
ethon (0.6.1)
ffi (>= 1.3.0)
mime-types (~> 1.18)
eventmachine (1.0.3)
execjs (2.0.2)
fattr (2.2.1)
ffi (1.9.0)
gemoji (1.4.0)
github-markdown (0.5.5)
highline (1.6.19)
hike (1.2.3)
html-pipeline (0.2.1)
escape_utils (~> 0.3)
gemoji (~> 1.0)
github-markdown (~> 0.5)
nokogiri (~> 1.4)
rinku (~> 1.7)
sanitize (~> 2.0)
i18n (0.6.5)
method_source (0.8.2)
mime-types (1.25)
mini_portile (0.5.1)
minitest (4.7.5)
multi_json (1.8.1)
nokogiri (1.6.0)
mini_portile (~> 0.5.0)
options (2.3.0)
fattr
progress_bar (1.0.0)
highline (~> 1.6.1)
options (~> 2.3.0)
pry (0.9.12.2)
coderay (~> 1.0.5)
method_source (~> 0.8)
slop (~> 3.4)
rack (1.5.2)
rack-protection (1.5.0)
rack
rack-test (0.6.2)
rack (>= 1.0)
rinku (1.7.3)
rr (1.1.2)
sanitize (2.0.6)
nokogiri (>= 1.4.4)
sass (3.2.12)
sinatra (1.4.3)
rack (~> 1.4)
rack-protection (~> 1.4)
tilt (~> 1.3, >= 1.3.4)
sinatra-contrib (1.4.1)
backports (>= 2.0)
multi_json
rack-protection
rack-test
sinatra (~> 1.4.0)
tilt (~> 1.3)
slop (3.4.6)
sprockets (2.10.0)
hike (~> 1.2)
multi_json (~> 1.0)
rack (~> 1.0)
tilt (~> 1.1, != 1.3.0)
sprockets-helpers (1.0.1)
sprockets (~> 2.0)
thin (1.6.0)
daemons (>= 1.0.9)
eventmachine (>= 1.0.0)
rack (>= 1.5.0)
thor (0.18.1)
thread_safe (0.1.3)
atomic
tilt (1.4.1)
typhoeus (0.6.5)
ethon (~> 0.6.1)
tzinfo (0.3.38)
uglifier (2.2.1)
execjs (>= 0.3.0)
multi_json (~> 1.0, >= 1.0.2)
unix_utils (0.0.15)
yajl-ruby (1.1.0)
PLATFORMS
ruby
DEPENDENCIES
activesupport (~> 4.0)
better_errors
browser
coffee-script
erubis
html-pipeline
minitest
nokogiri (~> 1.6.0)
progress_bar
pry (~> 0.9.12)
rack
rr
sass
sinatra
sinatra-contrib
sprockets
sprockets-helpers
thin
thor
typhoeus
uglifier
unix_utils
yajl-ruby
Mozilla Public License Version 2.0
==================================
1. Definitions
--------------
1.1. "Contributor"
means each individual or legal entity that creates, contributes to
the creation of, or owns Covered Software.
1.2. "Contributor Version"
means the combination of the Contributions of others (if any) used
by a Contributor and that particular Contributor's Contribution.
1.3. "Contribution"
means Covered Software of a particular Contributor.
1.4. "Covered Software"
means Source Code Form to which the initial Contributor has attached
the notice in Exhibit A, the Executable Form of such Source Code
Form, and Modifications of such Source Code Form, in each case
including portions thereof.
1.5. "Incompatible With Secondary Licenses"
means
(a) that the initial Contributor has attached the notice described
in Exhibit B to the Covered Software; or
(b) that the Covered Software was made available under the terms of
version 1.1 or earlier of the License, but not also under the
terms of a Secondary License.
1.6. "Executable Form"
means any form of the work other than Source Code Form.
1.7. "Larger Work"
means a work that combines Covered Software with other material, in
a separate file or files, that is not Covered Software.
1.8. "License"
means this document.
1.9. "Licensable"
means having the right to grant, to the maximum extent possible,
whether at the time of the initial grant or subsequently, any and
all of the rights conveyed by this License.
1.10. "Modifications"
means any of the following:
(a) any file in Source Code Form that results from an addition to,
deletion from, or modification of the contents of Covered
Software; or
(b) any new file in Source Code Form that contains any Covered
Software.
1.11. "Patent Claims" of a Contributor
means any patent claim(s), including without limitation, method,
process, and apparatus claims, in any patent Licensable by such
Contributor that would be infringed, but for the grant of the
License, by the making, using, selling, offering for sale, having
made, import, or transfer of either its Contributions or its
Contributor Version.
1.12. "Secondary License"
means either the GNU General Public License, Version 2.0, the GNU
Lesser General Public License, Version 2.1, the GNU Affero General
Public License, Version 3.0, or any later versions of those
licenses.
1.13. "Source Code Form"
means the form of the work preferred for making modifications.
1.14. "You" (or "Your")
means an individual or a legal entity exercising rights under this
License. For legal entities, "You" includes any entity that
controls, is controlled by, or is under common control with You. For
purposes of this definition, "control" means (a) the power, direct
or indirect, to cause the direction or management of such entity,
whether by contract or otherwise, or (b) ownership of more than
fifty percent (50%) of the outstanding shares or beneficial
ownership of such entity.
2. License Grants and Conditions
--------------------------------
2.1. Grants
Each Contributor hereby grants You a world-wide, royalty-free,
non-exclusive license:
(a) under intellectual property rights (other than patent or trademark)
Licensable by such Contributor to use, reproduce, make available,
modify, display, perform, distribute, and otherwise exploit its
Contributions, either on an unmodified basis, with Modifications, or
as part of a Larger Work; and
(b) under Patent Claims of such Contributor to make, use, sell, offer
for sale, have made, import, and otherwise transfer either its
Contributions or its Contributor Version.
2.2. Effective Date
The licenses granted in Section 2.1 with respect to any Contribution
become effective for each Contribution on the date the Contributor first
distributes such Contribution.
2.3. Limitations on Grant Scope
The licenses granted in this Section 2 are the only rights granted under
this License. No additional rights or licenses will be implied from the
distribution or licensing of Covered Software under this License.
Notwithstanding Section 2.1(b) above, no patent license is granted by a
Contributor:
(a) for any code that a Contributor has removed from Covered Software;
or
(b) for infringements caused by: (i) Your and any other third party's
modifications of Covered Software, or (ii) the combination of its
Contributions with other software (except as part of its Contributor
Version); or
(c) under Patent Claims infringed by Covered Software in the absence of
its Contributions.
This License does not grant any rights in the trademarks, service marks,
or logos of any Contributor (except as may be necessary to comply with
the notice requirements in Section 3.4).
2.4. Subsequent Licenses
No Contributor makes additional grants as a result of Your choice to
distribute the Covered Software under a subsequent version of this
License (see Section 10.2) or under the terms of a Secondary License (if
permitted under the terms of Section 3.3).
2.5. Representation
Each Contributor represents that the Contributor believes its
Contributions are its original creation(s) or it has sufficient rights
to grant the rights to its Contributions conveyed by this License.
2.6. Fair Use
This License is not intended to limit any rights You have under
applicable copyright doctrines of fair use, fair dealing, or other
equivalents.
2.7. Conditions
Sections 3.1, 3.2, 3.3, and 3.4 are conditions of the licenses granted
in Section 2.1.
3. Responsibilities
-------------------
3.1. Distribution of Source Form
All distribution of Covered Software in Source Code Form, including any
Modifications that You create or to which You contribute, must be under
the terms of this License. You must inform recipients that the Source
Code Form of the Covered Software is governed by the terms of this
License, and how they can obtain a copy of this License. You may not
attempt to alter or restrict the recipients' rights in the Source Code
Form.
3.2. Distribution of Executable Form
If You distribute Covered Software in Executable Form then:
(a) such Covered Software must also be made available in Source Code
Form, as described in Section 3.1, and You must inform recipients of
the Executable Form how they can obtain a copy of such Source Code
Form by reasonable means in a timely manner, at a charge no more
than the cost of distribution to the recipient; and
(b) You may distribute such Executable Form under the terms of this
License, or sublicense it under different terms, provided that the
license for the Executable Form does not attempt to limit or alter
the recipients' rights in the Source Code Form under this License.
3.3. Distribution of a Larger Work
You may create and distribute a Larger Work under terms of Your choice,
provided that You also comply with the requirements of this License for
the Covered Software. If the Larger Work is a combination of Covered
Software with a work governed by one or more Secondary Licenses, and the
Covered Software is not Incompatible With Secondary Licenses, this
License permits You to additionally distribute such Covered Software
under the terms of such Secondary License(s), so that the recipient of
the Larger Work may, at their option, further distribute the Covered
Software under the terms of either this License or such Secondary
License(s).
3.4. Notices
You may not remove or alter the substance of any license notices
(including copyright notices, patent notices, disclaimers of warranty,
or limitations of liability) contained within the Source Code Form of
the Covered Software, except that You may alter any license notices to
the extent required to remedy known factual inaccuracies.
3.5. Application of Additional Terms
You may choose to offer, and to charge a fee for, warranty, support,
indemnity or liability obligations to one or more recipients of Covered
Software. However, You may do so only on Your own behalf, and not on
behalf of any Contributor. You must make it absolutely clear that any
such warranty, support, indemnity, or liability obligation is offered by
You alone, and You hereby agree to indemnify every Contributor for any
liability incurred by such Contributor as a result of warranty, support,
indemnity or liability terms You offer. You may include additional
disclaimers of warranty and limitations of liability specific to any
jurisdiction.
4. Inability to Comply Due to Statute or Regulation
---------------------------------------------------
If it is impossible for You to comply with any of the terms of this
License with respect to some or all of the Covered Software due to
statute, judicial order, or regulation then You must: (a) comply with
the terms of this License to the maximum extent possible; and (b)
describe the limitations and the code they affect. Such description must
be placed in a text file included with all distributions of the Covered
Software under this License. Except to the extent prohibited by statute
or regulation, such description must be sufficiently detailed for a
recipient of ordinary skill to be able to understand it.
5. Termination
--------------
5.1. The rights granted under this License will terminate automatically
if You fail to comply with any of its terms. However, if You become
compliant, then the rights granted under this License from a particular
Contributor are reinstated (a) provisionally, unless and until such
Contributor explicitly and finally terminates Your grants, and (b) on an