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 From 650f0b54510b5aa6faa24c1ea7c670de15f40955 Mon Sep 17 00:00:00 2001 From: samcv Date: Wed, 26 Oct 2016 01:19:06 -0700 Subject: =?UTF-8?q?Remove=20the=20byte=20order=20mark=20from=20the=20Czech?= =?UTF-8?q?=20Javascript=20file.=20=20This=20file=E2=80=A6=20(#2509)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Remove the byte order mark from the Czech Javascript file. This file wasn't showing up on the site before but this will fix it :) * Add info on how to check if a file has a byte order marker to the CONTRIBUTING file * Fit into 80 columns width --- CONTRIBUTING.markdown | 3 +++ 1 file changed, 3 insertions(+) (limited to 'CONTRIBUTING.markdown') diff --git a/CONTRIBUTING.markdown b/CONTRIBUTING.markdown index 9ee33ebc..5fa1d03d 100644 --- a/CONTRIBUTING.markdown +++ b/CONTRIBUTING.markdown @@ -33,6 +33,9 @@ review them more effectively and/or individually. your file is UTF-8 encoded. + Try to leave out the byte-order-mark at the start of the file. (`:set nobomb` in Vim) + + You can check if the file contains a BOM on Linux/Unix systems by running + `file language.html.markdown` You will see this if it uses a BOM: + `UTF-8 Unicode (with BOM) text`. ### Header configuration -- cgit v1.2.3