mirror of
https://github.com/EbookFoundation/free-programming-books.git
synced 2024-12-22 19:36:13 +00:00
84438cb1df
* docs(contributing): remove trailing spaces * docs(contributing): Apply headings `2-1` empty lines lint rule * docs(contributing): Apply headings `2-1` empty lines lint rule forgotten in previous commit:e83220aa4c* docs(contributing): Move anchor alias to inside list items ... there where an anchor alias `<a name="...">` is used near to each of those list items This solves markdownlint `MD032/blanks-around-lists` issue * docs(contributing): Homogenize `1` blank line in nutshell enumeration * docs(contributing): Homogenize `1` blank line inside Formatting section * docs(contributing): Ensure `4-spaces` indent `.editorconfig` param * docs(contributing): Homogenize format & indent of code blocks - Format using fenced style. - Well indent in those placed inside list enumerations. - Simulate `Good` - `Bad` monospace double colon indent inside each one. - Examples highlighting as `text-plain`. The `md, markdown` style doesn't work very well since blocks has mixed syntax. - `check_urls` code block highlighted as `properties` style (key-value pair). Solves markdownlint rules: - MD040/fenced-code-language: Fenced code blocks should have a language specified - MD046/code-block-style: Code block style [Expected: indented; Actual: fenced] * docs(contributing): Ensure `4-spaces` indent `.editorconfig` param Forgotten in commit:31c776cb52* docs(contributing): Homogenize format & indent of code blocks - Simulate `Good` - `Bad` monospace double colon indent inside each one. Revert commitf9dc719aefonly in this file after check non-needs in a deployed web snapshot * docs(contributing): Use "consistent" unordered list mark Solves markdownlint rules: MD004/ul-style: Unordered list style "consistent" * docs(contributing): Solve `no-space-in-*` lint rules markdownlint rules: MD037/no-space-in-emphasis: Spaces inside emphasis MD038/no-space-in-code: Spaces inside code span elements MD039/no-space-in-links: Spaces inside link text * docs(contributing): Move some punctuation just before any closing brackets after it * docs(contributing): Hack highlight IDE/Editors headings+HTML It apply the hack to highlight in IDE/Editors those headings with an anchor alias just before itself * docs(contributing): Homogenize Pull Request acronym * docs(contributing): Fix `GitHub` trademark typos * docs(contributing): ALLCAPS * docs(contributing): Git trademark * docs(contributing): YouTube trademark * docs(contributing): ISBN acronym * fix: flag emoji code `en` > `us` Resolvesd775cb34fb (commitcomment-59537594)#5831: `:en:` emoji flag markup doesn't work. Use `🇺🇸` 🇺🇸 or `🇬🇧` 🇬🇧d775cb34fb (diff-b35eb40c148657d4ea1361c44496e11c5625f484a4c6040c022770e88cbcfdccR8-R10)* docs(contributing): Fix fa_IR broken anchors * docs(contributing): filenames in monospace font * docs(contributing): Homogenize `check_urls=file_to_check` * docs(contributing): literals/markup texts in monospace font - `et al.` - File extensions `.md` - Protocols: `http`, `https`... - Notes: LeanPub, require email, StackOverflow, in process, archived trailing dots in that lines * docs(contributing): linkify wayback machine * docs(contributing): Fix `Leanpub` trademark typos * chore: Rename `master` to `main` #blacklivesmatter Resolves EbookFoundation/free-programming-books#5803 * docs(contributing): fix broken ref link to `programming-playgrounds` Fix over EbookFoundation/free-programming-books#5449 and commit3c42c3629e(cherry picked from commit 59ebfe3f97e318fa43d58877cbc5bfdd8b0c7426) * docs(contributing): fix repo urls on initial FR translation - `ElivreFoundation` -> `EbookFoundation` - `free-programming-livres` ->`free-programming-books` PR: #5554 Commit:e629db6b05Affected lines: -18bb745c90 (diff-d6fa57ebb070f7f05f8c686a2fe92110652f48886774460ffee08d4be4cd5f27R4)//e629db6b05 (diff-d6fa57ebb070f7f05f8c686a2fe92110652f48886774460ffee08d4be4cd5f27R4)-18bb745c90 (diff-d6fa57ebb070f7f05f8c686a2fe92110652f48886774460ffee08d4be4cd5f27R7)//e629db6b05 (diff-d6fa57ebb070f7f05f8c686a2fe92110652f48886774460ffee08d4be4cd5f27R7)-18bb745c90 (diff-d6fa57ebb070f7f05f8c686a2fe92110652f48886774460ffee08d4be4cd5f27R13)//e629db6b05 (diff-d6fa57ebb070f7f05f8c686a2fe92110652f48886774460ffee08d4be4cd5f27R13)-18bb745c90 (diff-d6fa57ebb070f7f05f8c686a2fe92110652f48886774460ffee08d4be4cd5f27R45)//e629db6b05 (diff-d6fa57ebb070f7f05f8c686a2fe92110652f48886774460ffee08d4be4cd5f27R45)* docs(contributing): use relative urls EN Via #6614 * docs(contributing): greek. place translations link in right place Via #6614 * Merge EbookFoundation/free-programming-books#6631 upstream/main commit into docs/contributing/sync/1 * Add repo badges (see EbookFoundation/free-programming-books#5983) (cherry picked froma16a79b12dsolving merge conflict) * Merge EbookFoundation/free-programming-books#6662 upstream/main commit into docs/contributing/sync/1 * Apply centering proposed at #5983 but not implemented in #6631 (cherry picked from commitf36fd03c06) * format(contributing): Bold 5th nutshell equal zh * Merge #6677 upstream/main commit into docs/contributing/sync/1 fix(docs): Use Kramdown processor (#6677) * Update _config.yml * add markdown="1" * update url * complete removing spaces? * explicitly use kramdown (cherry picked from commitde2f31976f)
155 lines
13 KiB
Markdown
155 lines
13 KiB
Markdown
*[این متن را در زبان‌های دیگر بخوانید](../README.md#translations)*
|
|
|
|
|
|
<div dir="rtl" markdown="1">
|
|
|
|
## توافقنامه‌ی مجوز همکاری
|
|
|
|
مشارکت در این مخزن به معنی موافقت شما با مجوز [LICENSE](../LICENSE) این مخزن است.
|
|
|
|
|
|
## مرام‌نامه‌ی همکار
|
|
|
|
مشارکت در این پروژه به معنی موافقت با احترام به [مرام‌نامه‌ی](CODE_OF_CONDUCT-fa_IR.md) این مخزن است. ([translations](../README.md#translations))
|
|
|
|
|
|
## به طور خلاصه
|
|
|
|
1. "لینکی برای دانلود ساده‌ی یک کتاب" همیشه به معنی لینکی به یک کتاب *رایگان* نیست. لطفا فقط محتوای رایگان را قرار دهید. مطمئن شوید که این محتوا رایگان است. ما لینک‌هایی را که وارد کردن ایمیل کاری را برای دانلود کتاب *اجباری* کرده‌اند نمی‌پذیریم اما اگر بدون اجبار، این ایمیل را بخواهند، در این مخزن فهرستشان می‌کنیم.
|
|
|
|
2. نیاز نیست گیت بلد باشید: اگر چیز جذابی پیدا کردید که *در این مخزن وجود ندارد*، یک [Issue](https://github.com/EbookFoundation/free-programming-books/issues) با نوشتن لینک‌ها درست کنید.
|
|
* اگر Git را می شناسید، لطفاً مخزن را Fork کنید و درخواست های کششی (PR) ارسال کنید.
|
|
|
|
3. ما پنج نوع فهرست داریم. فهرست درست را انتخاب کنید:
|
|
|
|
* *کتاب‌ها* : PDF، HTML، ePub، سایت بر اساس gitbook.io، یک مخزن گیت و غیره.
|
|
* *دوره‌ها* : دوره محتوایی آموزشی است که کتاب نیست. مثلا [این یک دوره است](http://ocw.mit.edu/courses/electrical-engineering-and-computer-science/6-006-introduction-to-algorithms-fall-2011/).
|
|
* *آموزش‌های تعاملی* : وبسایتی تعاملی که به کاربر اجازه‌ی تایپ کد یا دستور می‌دهد و نتیجه را ارزیابی می‌کند (منظور ما از "ارزیابی"، "نمره‌دهی" نیست). مثلا: [Try Haskell](http://tryhaskell.org), [Try GitHub](http://try.github.io).
|
|
* *پادکست‌ها و اسکرین‌کست‌ها*
|
|
* *مجموعه مشکلات و برنامه‌نویسی رقابتی* : وبسایت یا نرم‌افزاری که به شما امکان بررسی مهارت‌های برنامه‌نویسی را با کمک حل مشکلات ساده یا پیچیده، با یا بدون بررسی کد، با یا بدون مقایسه‌ی نتایج با کاربران دیگر می‌دهد.
|
|
|
|
4. مطمئن شوید که از [راهنماها](#guidelines) پیروی می‌کنید و طبق [فرمت‌بندی مارک‌داون](#formatting) می‌نویسید.
|
|
|
|
5. GitHub Actions تست‌هایی را اجرا می‌کند که مطمئن شود **فهرست شما الفبایی است** و **قوانین فرمت‌بندی رعایت شده است**. **مطمئن شوید که** تغییرات شما تست‌ها را با موفقیت گذرانده است.
|
|
|
|
|
|
<!----><a name="guidelines"></a>
|
|
### راهنماها
|
|
|
|
* مطمئن شوید که یک کتاب رایگان است. اگر لازم بود، دوباره هم بررسی کنید. اگر درباره‌ی علت این که فکر می‌کنید کتاب رایگان است در پول‌ریکوئست (PR)، کامنت بگذارید، به ادمین‌ها کمک کرده‌اید.
|
|
* ما فایل‌هایی را قبول نمی‌کنیم که روی گوگل‌درایو، دراپ‌باکس، مگا، اسکریبد، ایسیو یا پلتفرم‌های آپلود فایل مشابه قرار دارند
|
|
* لینک‌های خود را به ترتیب الفبایی وارد کنید. اگر لینکی را خارج از ترتیب درست دیدید، لطفا مرتیش کنید و یک پی‌آر ثبت کنید
|
|
* از لینک معتبرترین منبع استفاده کنید (این یعنی وبسایت نویسنده بهتر از وبسایت ویراستار و وبسایت ویراستار بهتر از وبسایت سوم شخص است)
|
|
* از سرویس‌های اشتراک‌گذاری فایل استفاده نکنید (این سرویس‌ها شامل (و نه محدود به) لینک‌های دراپ‌باکس و گوگل‌درایو است)
|
|
* همیشه یک لینک `https` به یک لینک `http` ترجیح داده می‌شود -- تا وقتی که هر دو لینک دامنه‌ی یکسانی داشته باشند و محتوای یکسانی نمایش دهند.
|
|
* در دامنه‌های اصلی، از گذاشتن / خودداری کنید: `http://example.com` به جای `http://example.com/`
|
|
* همیشه کوتاه‌ترین لینک ترجیح داده می‌شود: `http://example.com/dir/` بهتر است از `http://example.com/dir/index.html`
|
|
* از لینک‌های کوتاه‌ساز استفاده نکنید.
|
|
* معمولا لینک "فعلی" بهتر از لینک "نسخه‌ها" است: `http://example.com/dir/book/current/` بهتر است از `http://example.com/dir/book/v1.0.0/index.html`
|
|
* اگر لینکی مشکل certificate/self-signed certificate/SSL از هر نوع دیگری داشت:
|
|
1. با همتای `http` همان لینک *جایگزینش کنید* (چون پذیرش استثناقائل شدن برای آن وبسایت در دستگاه‌های موبایل سخت است).
|
|
2. اگر نسخه‌ی `http` ندارد اما همچنان با `https` و اضافه کردن استثناقائل‌شدن برای آن وبسایت در مرورگر یا نادیده گرفتن هشدار قابل دسترس است، *به همان حالت بگذاریدش*
|
|
3. در غیر این صورت *حذفش کنید*
|
|
* اگر لینکی در چندین فرمت وجود داشت، لینکی جدا با یادداشتی درباره‌ی هر فرمت قرار دهید.
|
|
* اگر منبعی در جاهای دیگری از اینترنت وجود دارد
|
|
* از لینک معتبرترین منبع استفاده کنید (این یعنی وبسایت نویسنده بهتر از وبسایت ویراستار و وبسایت ویراستار بهتر از وبسایت سوم شخص است)
|
|
* اگر به ویرایش‌های مختلف لینک شده است و شما معتقدید این ویرایش‌ها به حد کافی متفاوت هستند که هر دو نگه داشته شوند، یک لینک جدا با یادداشتی درباره‌ی هر ویرایش بنویسید (برای مشارکت در فرمت‌بندی [Issue #2353](https://github.com/EbookFoundation/free-programming-books/issues/2353) را ببینید).
|
|
* کامیت‌های تکی (یک کامیت اضافه کردن/ حذف کردن/ تغییر دادن) بهتر از کامیت‌های بزرگ هستند. نیاز نیست کامیت‌های خود را قبل از ثبت یک پی‌آر خرد کنید (ما به دنبال اجباری کردن این قانون نیستیم چون این قانون فقط به خاطر راحتی نگه‌دارندگان مخزن است)
|
|
* اگر کتاب قدیمی است، تاریخ انتشار را در کنار عنوان بنویسید.
|
|
* نام نویسنده یا نویسندگان را در صورت امکان بنویسید. می‌توانید فهرست نویسندگان را با "و همکاران" (به انگلیسی: "`et al.`") کوتاه کنید.
|
|
* اگر کتاب هنوز تمام نشده است و هنوز روی آن کار می‌شود، عبارت "`in process`" را همان طور که در [پایین صفحه](#in_process) آمده به آن اضافه کنید.
|
|
* اگر پیش از دانلود، نشانی ایمیل یا ساخت حساب کاربری خواسته می‌شود، در پرانتز توضیح متناسبی بنویسید. مثلا: `(نشانی ایمیل *خواسته می‌شود* اما اجباری نیست)`.
|
|
|
|
|
|
<!----><a name="formatting"></a>
|
|
### فرمت‌بندی
|
|
|
|
* همه فهرست‌ها فایل‌های ".md" هستند. سعی کنید دستور زبان [Markdown](https://guides.github.com/features/mastering-markdown/) را یاد بگیرید. ساده است!
|
|
* همه فهرست‌ها با یک فهرست محتوایی شروع می‌شود. ایده این است که همه بخش‌ها و زیربخش‌ها در این فهرست محتوایی لیست و لینک شوند. این فهرست محتوایی را به ترتیب الفبایی قرار دهید.
|
|
* بخش‌ها از تیترهای سطح 3 (`###`) استفاده می‌کنند و زیربخش‌ها از تیترهای سطح 4 (`###`).
|
|
|
|
ایده این است که این موارد رعایت شوند:
|
|
|
|
* `2` خط خالی بین آخرین لینک و بخش جدید
|
|
* `1` خط خالی بین تیتر و لینک اول همان بخش
|
|
* `0` خط خالی بین دو لینک
|
|
* `1` خط خالی در آخر هر فایل `.md`
|
|
|
|
مثال:
|
|
|
|
```text
|
|
[...]
|
|
* [یک کتاب عالی](http://example.com/example.html)
|
|
(خط خالی)
|
|
(خط خالی)
|
|
### مثال
|
|
(خط خالی)
|
|
* [یک کتاب عالی دیگر](http://example.com/book.html)
|
|
* [یک کتاب دیگر](http://example.com/other.html)
|
|
```
|
|
|
|
* بین `]` و `(` space نگذارید:
|
|
|
|
```text
|
|
بد : * [یک کتاب عالی دیگر] (http://example.com/book.html)
|
|
خوب: * [یک کتاب عالی دیگر](http://example.com/book.html)
|
|
```
|
|
|
|
* اگر اسم نویسنده را اضافه می‌کنید، از ` - ` استفاده کنید (یک dash با دو single space):
|
|
|
|
```text
|
|
بد : * [یک کتاب عالی دیگر](http://example.com/book.html)- نام نویسنده
|
|
خوب: * [یک کتاب عالی دیگر](http://example.com/book.html) - نام نویسنده
|
|
```
|
|
|
|
* یک single space بین لینک و فرمت قرار دهید:
|
|
|
|
```text
|
|
بد : * [یک کتاب خیلی عالی](https://example.org/book.pdf)(PDF)
|
|
خوب: * [یک کتاب خیلی عالی](https://example.org/book.pdf) (PDF)
|
|
```
|
|
|
|
* نویسنده قبل از فرمت می‌آید:
|
|
|
|
```text
|
|
بد : * [یک کتاب خیلی عالی](https://example.org/book.pdf)- (PDF) نام نویسنده
|
|
خوب: * [یک کتاب خیلی عالی](https://example.org/book.pdf) - یک نویسنده دیگر (PDF)
|
|
```
|
|
|
|
* چند فرمتی‌ها:
|
|
|
|
```text
|
|
بد : * [یک کتاب عالی دیگر](http://example.com/)- نام نویسنده (HTML)
|
|
بد : * [یک کتاب عالی دیگر](https://downloads.example.org/book.html)- نام نویسنده (download site)
|
|
خوب: * [یک کتاب عالی دیگر](http://example.com/) - نام نویسنده (HTML) [(PDF, EPUB)](https://downloads.example.org/book.html)
|
|
```
|
|
|
|
* سال انتشار برای کتاب‌های قدیمی را در عنوان ینویسید:
|
|
|
|
```text
|
|
بد : * [یک کتاب خیلی عالی](https://example.org/book.html) - نام نویسنده - 1970
|
|
خوب: * [یک کتاب خیلی عالی (1970)](https://example.org/book.html) - نام نویسنده
|
|
```
|
|
|
|
* <a name="in_process"></a>کتاب‌های در دست تالیف:
|
|
|
|
```text
|
|
خوب: * [کتابی که عالی خواهدشد](http://example.com/book2.html) - نام نویسنده (HTML) (:construction: *in process*)
|
|
```
|
|
|
|
|
|
### خودکارسازی
|
|
|
|
* قوانین فرمت‌بندی از طریق [GitHub Actions](https://docs.github.com/en/actions) با استفاده از [fpb-lint](https://github.com/vhf/free-programming-books-lint) بررسی می‌شوند ([`.github/workflows/fpb-lint.yml`](.github/workflows/fpb-lint.yml) را ببینید)
|
|
* اعتبارسنجی لینک‌ها با استفاده از [awesome_bot](https://github.com/dkhamsing/awesome_bot) انجام می‌شود.
|
|
* برای اجرای اعتبارسنجی لینک‌ها، کامیتی پوش کنید که در بدنه‌ی آن `check_urls=file_to_check` نوشته شده باشد:
|
|
|
|
```properties
|
|
check_urls=free-programming-books.md free-programming-books-fa_IR.md
|
|
```
|
|
|
|
* با استفاده از single space برای جدا کردن هر ورودی، می‌توانید بیشتر از یک فایل را برای بررسی مشخص کنید.
|
|
* اگر بیش از یک فایل را مشخص کردید، نتایج بیلد بر اساس نتیجه آخرین فایل بررسی‌شده خواهد بود. دقت کنید که ممکن است به همین علت، نتیجه سبز را ببینید. پس برای اطمینان لاگ بیلد را با کلیک روی "Show all checks" -> "Details" در پایان پول ریکوئست (PR) ببینید.
|
|
|
|
</div>
|