info/learnxinyminutes-docs
1
0
Fork 0
mirror of https://github.com/adambard/learnxinyminutes-docs.git synced 2025-08-23 06:43:37 +02:00
Code Issues Releases Wiki Activity

Merge pull request #4556 from nbehrnd/contributing

Browse Source 
CONTRIBUTING, lint and hint to markdownlint
This commit is contained in:
Marcel Ribeiro Dantas
2022-11-30 13:06:00 -03:00
committed by GitHub
parent 5142de01e3 23a2d02f7f
commit 7b623a7998
1 changed files with 50 additions and 44 deletions
Download Patch File Download Diff File Expand all files Collapse all files

94
CONTRIBUTING.markdown
View File

@@ -16,27 +16,29 @@ review them more effectively and/or individually.
## Style Guidelines ## Style Guidelines
- **Keep lines under 80 chars** * **Keep lines under 80 chars**
+ Try to keep **line length in code blocks to 80 characters or fewer**. * Try to keep **line length in code blocks to 80 characters or fewer**.
+ Otherwise, the text will overflow and look odd. * Otherwise, the text will overflow and look odd.
- **Prefer example to exposition** * This and other potential pitfalls to format the content consistently are
+ Try to use as few words as possible. identified by the freely available
+ Code examples are preferred over exposition in all cases. [markdownlint](https://github.com/markdownlint/markdownlint).
- **Eschew surplusage** * **Prefer example to exposition**
+ We welcome newcomers, but the target audience for this site is programmers * Try to use as few words as possible.
with some experience. * Code examples are preferred over exposition in all cases.
+ Try to avoid explaining basic concepts except for those specific to the * **Eschew surplusage**
language in question. * We welcome newcomers, but the target audience for this site is programmers
+ Keep articles succinct and scannable. We all know how to use Google here. with some experience.
- **Use UTF-8** * Try to avoid explaining basic concepts except for those specific to the
+ For translations (or EN articles with non-ASCII characters) please make sure language in question.
your file is UTF-8 encoded. * Keep articles succinct and scannable. We all know how to use Google here.
+ Try to leave out the byte-order-mark at the start of the file. (`:set nobomb` * **Use UTF-8**
in Vim) * For translations (or EN articles with non-ASCII characters) please ensure
+ You can check if the file contains a BOM on Linux/Unix systems by running your file is UTF-8 encoded.
* Try to leave out the byte-order-mark at the start of the file (in Vim, use
`:set nobomb`).
* 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: `file language.html.markdown` You will see this if it uses a BOM:
`UTF-8 Unicode (with BOM) text`. `UTF-8 Unicode (with BOM) text`.
### Header configuration ### Header configuration
@@ -47,31 +49,31 @@ some key information be defined in the header.
The following fields are necessary for English articles about programming The following fields are necessary for English articles about programming
languages: languages:
- **language** The *programming language* in question * **language** The *programming language* in question
- **contributors** A list of [author, URL] lists to credit * **contributors** A list of [author, URL] lists to credit
Other fields: Other fields:
- **category**: The category of the article. So far, can be one of *language*, * **category**: The category of the article. So far, can be one of *language*,
*tool* or *Algorithms & Data Structures*. Defaults to *language* if omitted. *tool* or *Algorithms & Data Structures*. Defaults to *language* if omitted.
- **filename**: The filename for this article's code. It will be fetched, mashed * **filename**: The filename for this article's code. It will be fetched, mashed
together, and made downloadable. together, and made downloadable.
+ For non-English articles, *filename* should have a language-specific * For non-English articles, *filename* should have a language-specific
suffix. suffix.
- **lang**: For translations, the human language this article is in. For * **lang**: For translations, the human language this article is in. For
categorization, mostly. categorization, mostly.
Here's an example header for an Esperanto translation of Ruby: Here's an example header for an Esperanto translation of Ruby:
```yaml ```yaml
--- *--
language: ruby language: ruby
filename: learnruby-epo.ruby filename: learnruby-epo.ruby
contributors: contributors:
- ["Doktor Esperanto", "http://example.com/"] - ["Doktor Esperanto", "http://example.com/"]
- ["Someone else", "http://someoneelseswebsite.com/"] - ["Someone else", "http://someoneelseswebsite.com/"]
lang: ep-ep lang: ep-ep
--- *--
``` ```
### Should I add myself as a Contributor? ### Should I add myself as a Contributor?
@@ -85,21 +87,25 @@ addition or not.
You can build the site locally to test your changes. Follow the steps below. You can build the site locally to test your changes. Follow the steps below.
* Install Ruby language runtime and RubyGems. See [here](https://middlemanapp.com/basics/install/) for more details. * Install Ruby language runtime and RubyGems. See
* Clone or zip download the [learnxinyminutes-site](https://github.com/adambard/learnxinyminutes-site) repo. [here](https://middlemanapp.com/basics/install/)
* `git clone https://github.com/adambard/learnxinyminutes-site` for more details.
* Clone or zip download the
[learnxinyminutes-site](https://github.com/adambard/learnxinyminutes-site)
repository.
* `git clone https://github.com/adambard/learnxinyminutes-site`
* Install Middleman and other required dependencies using Bundler. * Install Middleman and other required dependencies using Bundler.
* `cd learnxinyminutes-site/` * `cd learnxinyminutes-site/`
* `bundle install` * `bundle install`
* Get the source in place * Get the source in place
* Copy the contents of your clone of the fork of learnxinyminutes-docs repo * Copy the contents of your clone of the fork of learnxinyminutes-docs repo
into the `source/docs` folder. There shouldn't be a `learnxinyminutes-docs` into the `source/docs` folder. There shouldn't be a `learnxinyminutes-docs`
folder inside the `docs` folder, it should just contain all the repo folder inside the `docs` folder, it should just contain all the repo
contents. contents.
* Checkout your fork of the learnxinyminutes-docs repo as `source/docs`. * Checkout your fork of the learnxinyminutes-docs repo as `source/docs`.
* `cd source/docs/` * `cd source/docs/`
* `git clone https://github.com/YOUR-USERNAME/learnxinyminutes-docs ./source/docs/` * `git clone https://github.com/YOUR-USERNAME/learnxinyminutes-docs ./source/docs/`
* Build the site or run a development server to test your changes (NOTE: run * Build the site or run a development server to test your changes (NOTE: run
these commands at `learnxinyminutes-site/`). these commands at `learnxinyminutes-site/`).
* Build - `bundle exec middleman build` * Build - `bundle exec middleman build`
* Dev server - `bundle exec middleman --force-polling --verbose` * Dev server - `bundle exec middleman --force-polling --verbose`