iskm/learnxinyminutes-docs
1
0
Fork 0
mirror of https://github.com/adambard/learnxinyminutes-docs.git synced 2024-12-23 09:41:36 +00:00
Code Issues Actions Packages Projects 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
commit 7b623a7998
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 50 additions and 44 deletions
Show Stats 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
- **Keep lines 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)
+ You can check if the file contains a BOM on Linux/Unix systems by running
* **Keep lines under 80 chars**
* Try to keep **line length in code blocks to 80 characters or fewer**.
* Otherwise, the text will overflow and look odd.
* This and other potential pitfalls to format the content consistently are
identified by the freely available
[markdownlint](https://github.com/markdownlint/markdownlint).
* **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 ensure
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:
`UTF-8 Unicode (with BOM) text`.
`UTF-8 Unicode (with BOM) text`.
### Header configuration
@ -47,31 +49,31 @@ some key information 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] lists to credit
* **language** The *programming language* in question
* **contributors** A list of [author, URL] lists to credit
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.
- **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.
+ For non-English articles, *filename* should have a language-specific
suffix.
- **lang**: For translations, the human language this article is in. For
* 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
---
*--
```
### 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.
* Install Ruby language runtime and RubyGems. See [here](https://middlemanapp.com/basics/install/) for more details.
* Clone or zip download the [learnxinyminutes-site](https://github.com/adambard/learnxinyminutes-site) repo.
* `git clone https://github.com/adambard/learnxinyminutes-site`
* Install Ruby language runtime and RubyGems. See
[here](https://middlemanapp.com/basics/install/)
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.
* `cd learnxinyminutes-site/`
* `bundle install`
* `cd learnxinyminutes-site/`
* `bundle install`
* Get the source in place
* 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`
folder inside the `docs` folder, it should just contain all the repo
contents.
* Checkout your fork of the learnxinyminutes-docs repo as `source/docs`.
* `cd source/docs/`
* `git clone https://github.com/YOUR-USERNAME/learnxinyminutes-docs ./source/docs/`
* 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`
folder inside the `docs` folder, it should just contain all the repo
contents.
* Checkout your fork of the learnxinyminutes-docs repo as `source/docs`.
* `cd 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
these commands at `learnxinyminutes-site/`).
* Build - `bundle exec middleman build`
* Dev server - `bundle exec middleman --force-polling --verbose`
these commands at `learnxinyminutes-site/`).
* Build - `bundle exec middleman build`
* Dev server - `bundle exec middleman --force-polling --verbose`