From cffb7e6770b517a620115b3a9e1f82ca1dd82a98 Mon Sep 17 00:00:00 2001 From: Hunter Stevens Date: Fri, 23 Oct 2015 14:25:42 -0400 Subject: Add contributing-specific file --- CONTRIBUTING.markdown | 58 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 CONTRIBUTING.markdown (limited to 'CONTRIBUTING.markdown') diff --git a/CONTRIBUTING.markdown b/CONTRIBUTING.markdown new file mode 100644 index 00000000..d7468898 --- /dev/null +++ b/CONTRIBUTING.markdown @@ -0,0 +1,58 @@ +# Contributing + +All contributions are welcome, from the tiniest typo to a brand new article. Translations +in all languages are welcome (or, for that matter, original articles in any language). +Send a pull request or open an issue any time of day or night. + +**Please prepend the tag `[language/lang-code]` to your issues and pull requests.** For example, +`[python/en]` for English Python. This will help everyone pick out things they care about. + +We're happy for any contribution in any form, but if you're making more than one major change +(i.e. translations for two different languages) it would be super cool of you to make a +separate pull request for each one so that someone can review them more effectively and/or +individually. + +## Style Guidelines + +- **Keep lines of under 80 chars** + + Try to keep **line length in code blocks to 80 characters or fewer**. + + Otherwise, the text will overflow and look odd. +- **Prefer example to exposition** + + Try to use as few words as possible. + + Code examples are preferred over exposition in all cases. +- **Eschew surplusage** + + We welcome newcomers, but the target audience for this site is programmers with some experience. + + Try to avoid explaining basic concepts except for those specific to the language in question. + + Keep articles succinct and scannable. We all know how to use Google here. +- **Use UTF-8** + + For translations (or EN articles with non-ASCII characters) please make sure your file is UTF-8 encoded. + + Try to leave out the byte-order-mark at the start of the file. (`:set nobomb` in Vim) + +## Header configuration + +The actual site uses Middleman to generate HTML files from these Markdown ones. Middleman, or at least +the custom scripts underpinning the site, requires key information to be defined in the header. + +The following fields are necessary for English articles about programming languages: + +- **language** - The *programming language* in question +- **contributors** - A list of [author, URL] arrays to provide credit + +Other fields: + +- **filename** - The filename for this article's code. It will be fetched, mashed together, and made downloadable. + + For non-English articles, *filename* should have a language-specific suffix. +- **lang** - For translations, the human language this article is in. For categorization, mostly. + +Here's an example header for an Esperanto translation of Ruby: + +```yaml +--- +language: ruby +filename: learnruby-epo.ruby +contributors: + - ["Doktor Esperanto", "http://example.com/"] + - ["Someone else", "http://someoneelseswebsite.com/"] +lang: ep-ep +--- +``` -- cgit v1.2.3