ملف التعليمات

يحتوي ملف README على معلومات وصفية حول محتوى المجلد الذي يوجد فيه. يشمل نطاق هذه المعلومات عادةً ملفات المجلد، وقد يشمل المجلدات الفرعية، أو حتى شجرة المجلدات بأكملها. يهدف الاسم إلى لفت انتباه المستخدم إلى معلومات مهمة وإرشادية حول محتوى المجلد. يُنصح من ليس لديه دراية بمحتوى المجلد بقراءة ملف README قبل قراءة الملفات الأخرى. على الرغم من شيوع استخدام اسم README، إلا أن هناك العديد من الأسماء المشابهة المستخدمة لنفس الغرض، مثل "Read Me" و"READ.ME". أحيانًا يتضمن اسم الملف امتدادًا للإشارة إلى تنسيق الملف ، مثل "README.txt" للنصوص العادية أو "README.md" لملفات Markdown . ^{[ 1 ]} غالبًا ما يكون اسم الملف مكتوبًا بأحرف كبيرة .

يعمل ملف README الموجود في الأرشيف بنفس طريقة عمله في الدليل، لأن الأرشيف يشبه الدليل المخزن كملف واحد.

محتوى

نظراً لافتقارها إلى التوحيد القياسي، يختلف تنسيق ومحتوى ملف README اختلافاً كبيراً. بالنسبة لمشروع برمجي ، يتضمن ملف README عادةً معلومات مثل:

تعليمات التكوين
تعليمات التركيب
تعليمات التشغيل
بيان الملفات (قائمة بالملفات الموجودة في الدليل أو الأرشيف)
معلومات حقوق النشر والترخيص
معلومات الاتصال بالموزع أو المؤلف
قائمة بالأخطاء المعروفة ^{[ 2 ]}
تعليمات استكشاف الأخطاء وإصلاحها ^{[ 2 ]}
الشكر والتقدير
سجل التغييرات (عادةً ما يكون موجهاً لزملائه المبرمجين)
قسم الأخبار (عادةً ما يكون موجهاً للمستخدمين النهائيين )

تاريخ

بدأ استخدام ملف README في منتصف سبعينيات القرن العشرين. ^{[ 3 ]}^{[ 4 ]}^{[ 5 ]}^{[ 6 ]}^{[ 7 ]}^{[ 8 ]}^{[ 9 ]} في نظام يونكس ، حيث كانت معظم أسماء الملفات تُكتب بأحرف صغيرة، كان يُكتب الاسم بحرف كبير ليبرز ويظهر قرب بداية القوائم المرتبة حسب ترتيب ASCII . كانت برامج نظام ماكنتوش القديمة تُثبّت ملف README على قرص بدء التشغيل، وكانت ملفات README تُرفق عادةً مع برامج الطرف الثالث.

على وجه الخصوص، هناك تاريخ طويل للبرمجيات الحرة والبرمجيات مفتوحة المصدر التي تتضمن ملف README؛ وتشجع معايير ترميز GNU على تضمين ملف README لتوفير "نظرة عامة على الحزمة". ^{[ 10 ]}

منذ ظهور الويب كمنصة قياسية فعلية لتوزيع البرامج ، قامت العديد من حزم البرامج بنقل (أو في بعض الأحيان نسخ) بعض الملفات والمعلومات الإضافية المذكورة أعلاه إلى موقع ويب أو ويكي ، وأحيانًا تتضمن ملف README نفسه، أو أحيانًا تترك وراءها ملف README موجز فقط بدون جميع المعلومات التي يحتاجها المستخدم الجديد للبرنامج.

يشجع موقع GitHub الشهير لاستضافة أكواد المصادر بشدة على إنشاء ملف README ؛ فإذا وُجد في الدليل الرئيسي (المستوى الأعلى) للمستودع، يُعرض تلقائيًا على الصفحة الرئيسية للمستودع. ^[¹¹^] بالإضافة إلى النص العادي، يدعم الموقع أيضًا العديد من التنسيقات وامتدادات الملفات الأخرى، ^[¹²^] ويأخذ تحويل HTML الامتدادات في الاعتبار ، حيث يُعامل ملف README.md تحديدًا على أنه ملف Markdown بنكهة GitHub .

تُخزَّن بيانات تعريف محتوى الدليل أحيانًا في ملفات بالإضافة إلى ملف README أو بدلاً منه. ^{[ 13 ]} يسرد الجدول التالي أسماء الملفات الشائعة الاستخدام ومحتواها. وكما هو الحال مع ملف README، لا توجد معايير رسمية تحكم أسماء الملفات أو محتواها. ومع ذلك، توجد اصطلاحات مُحدَّدة وفقًا لمعايير Gnits وأدوات GNU Autotools .

ملف التعليمات	معلومات عامة
المؤلفون	الشكر والتقدير
شكرًا	شكر وتقدير
سجل التغييرات	سجل تغييرات مفصل، مخصص للمبرمجين
أخبار	سجل تغييرات أساسي، مخصص للمستخدمين
ثَبَّتَ	تعليمات التركيب
حقوق النسخ/الترخيص	معلومات حقوق النشر والترخيص
الأخطاء	الأخطاء المعروفة وتعليمات الإبلاغ عن الأخطاء الجديدة
المساهمة/الاختراق	دليل للمساهمين المحتملين في المشروع
التعليمات	الأسئلة والأجوبة الشائعة
قائمة المهام	التغييرات المخطط لها

انظر أيضاً

مراجع

↑ ريموند، إريك ستيفن (1996). قاموس المخترق الجديد . مطبعة معهد ماساتشوستس للتكنولوجيا . الصفحات 378-379 . ISBN 978-0-26268092-9مقدمة من منظور المخترقين ، والتي تُدرج عادةً في الدليل الرئيسي لتوزيعة مصدر يونكس، تحتوي على مؤشر إلى وثائق أكثر تفصيلاً، ومعلومات عن المساهمين، وسجل المراجعات المتنوعة، والملاحظات، وما إلى ذلك. [...] عندما يُسألون، يربط المخترقون دائمًا اتفاقية README بالمشهد الشهير في مغامرات أليس في بلاد العجائب للويس كارول، حيث تواجه أليس وجبات خفيفة سحرية تحمل اسمي "كلني" و"اشربني".
1 2 مانس، ستيفن (نوفمبر 1996). "اقرأني؟ بالتأكيد - قبل أن أشتري!". عالم الكمبيوتر الشخصي . 14 (11): 366.
↑ "أرشيف PDP-10: decus/20-0079/readme.txt من decus_20tap3_198111" . pdp-10.trailing-edge.com . 27-11-1974 . تم الاسترجاع في 3-03-2018 . [README.TXT هو ملف DOC الخاص ببرامج SPICE/SINC/SLIC]. يحتوي هذا الشريط الاحتياطي على برامج تحليل الدوائر SPICE SINC وSLIC الموصوفة في نشرة برامج التطبيقات، المجلد 4. المتطلبات: يتطلب برنامج SPICE لغة FORTRAN-10 الإصدار 4 نظرًا لاستخدامه بيانات هوليريث المعدلة لليمين. يستغرق تنفيذه حوالي 47 كيلوبايت. [...] يتضمن أيضًا هذا الملف، وملفات FOROTS المصاحبة لملفات SAVes، ومصدر برنامج SECOND.MAC، وهو روتين التوقيت. ينقسم برنامج SPICE إلى ثلاثة أجزاء: 1SPICE.FOR، 2 و3. يوجد مستند مطبوع يشرح كل برنامج منها، وهو مُضمّن في حزمة DECUS. طُوّرت الوثائق والبرامج في الأصل من قِبل قسم الهندسة الكهربائية بجامعة كاليفورنيا في بيركلي على جهاز CDC 6400. باستثناء تحويل لغة FORTRAN إلى نظام DECsystem-10، لم تُجرَ أي تغييرات على البرامج. بالنسبة لبيانات الاختبار، أظهر برنامجا SLIC وSINC اختلافًا طفيفًا مقارنةً بجهاز 6400، بينما لم يُظهر برنامج SPICE أي اختلاف. بالتوفيق! آشلي غرايسون، 27 نوفمبر 1974 [نهاية ملف README.TXT]
↑ "DECUS 10-LIB-4 يحتوي على الملفات من 10-210 إلى 10-241، باستثناء الملف 10-223" . pdp-10.trailing-edge.com . 27-03-1975 . تاريخ الاسترجاع: 03-03-2018 . تُشكّل الملفات الموجودة على شريط FAILSAFE هذا نظام UCI LISP. وهي موثقة في معظمها في دليل UCI LISP، المتوفر من قسم علوم المعلومات والحاسوب في جامعة كاليفورنيا، إرفاين، كاليفورنيا.
↑ "Programmer's Workbench /sys/source/lex/README" . يوليو 1977. تم الاطلاع عليه بتاريخ 25 يناير 2020 .
↑ "Unix الإصدار السابع /usr/doc/README" . 1979. تم الاطلاع عليه بتاريخ 25-01-2020 .
↑ "أول ملف README لنظام BSD 32 بت usr/doc/" . مارس 1980. تم الاطلاع عليه بتاريخ 25 يناير 2020 .
↑ لانغماير، جيف (29 يوليو 2011). "رد: أصل ملف README" . تم الاطلاع عليه بتاريخ 25 يناير 2020 عبر Stackexchange. [...] كان لديهم ملفات README (ملفات مطبوعة فعلية) لجميع بطاقات التثقيب وأشرطة التسجيل المغناطيسية، وأي شيء آخر يُعتبر "برنامجًا". في ذلك الوقت، كان وجود ملف README ضروريًا نظرًا للعملية الشاقة التي كانت تتطلبها عملية إنشاء البرنامج وتشغيله وكل ما يتعلق به. تضمنت ملفات README هذه أحيانًا أيضًا مطبوعات توضح كيفية تثقيب بطاقات التثقيب كشكل من أشكال التحقق من الأخطاء وتصحيحها. يبدو أن هذا النظام يتبع النظام القديم أيضًا، حيث كان يتم إرفاق "حزمة" من الورق مع كل بطاقة تثقيب، مطبوع عليها عبارة README بأحرف كبيرة، والتي كانت تحتوي على جميع تعليمات استخدام بطاقات التثقيب وتحميلها في النظام. للمقارنة الزمنية، كان ذلك في الستينيات. [...]
↑ عبد الحفيظ، عمر (13 أغسطس 2015). "README.md: التاريخ والمكونات" . تم الاطلاع عليه بتاريخ 25 يناير 2020 .{{cite web}}: CS1 maint: deprecated archiveal service ( link )
↑ "معايير ترميز جنو: الإصدارات" . www.gnu.org . تم الاطلاع عليه بتاريخ 2018-03-03 .
↑ "حول ملفات README" . وثائق GitHub . تم الاطلاع عليه بتاريخ 31-05-2024 .
↑ "الترميز" . جيت هاب . 25-12-2014 . تم الاسترجاع في 8-02-2015 .
↑ برانا، جيدي أرثا أزريادي؛ ترويدي، كريستوف؛ ثونغ، فرديان؛ أتاباتو، ثوشاري؛ لو، ديفيد (2019-06-01). "تصنيف محتوى ملفات README على GitHub" . هندسة البرمجيات التجريبية . 24 (3): 1296-1327 . arXiv : 1802.06997 . doi : 10.1007/s10664-018-9660-3 . ISSN 1573-7616 .

للمزيد من القراءة

جونسون، مارك (1997-02-01). "بناء ملف ReadMe أفضل". الاتصالات التقنية . 44 (1). جمعية الاتصالات التقنية : 28-36 . JSTOR 43089849 .
ريسينيو، جين (أغسطس 1997). "النص التشعبي خيار جيد لملفات README". الاتصالات التقنية . 44 (3). جمعية الاتصالات التقنية : 214. JSTOR 43089876 .
ليفينغستون، برايان (14 سبتمبر 1998). "تحقق من ملفات Readme لتجنب مشاكل ويندوز الشائعة" . إنفوورلد . المجلد 20، العدد 37. مجموعة إنفوورلد الإعلامية، ص 34. مؤرشف من الأصل بتاريخ 18 نوفمبر 2006. تم الاطلاع عليه بتاريخ 4 يونيو 2019 .
بنيامين، أندرو (15 سبتمبر 1996) [1993]. كُتب في قسم الفلسفة، جامعة وارويك ، المملكة المتحدة. غيدون، جان كلود (محرر). "اقرأني: تدوين الملاحظات - تأملات في زمنية الكتابة" . مجلة Surfaces (مجلة إلكترونية) (باللغتين الإنجليزية والفرنسية). المجلد الثالث (12). جامعة مونتريال ، مونتريال (كيبيك)، كندا: Les Presses de l'Université de Montréal : 1-12 . الرقم الدولي الموحد للدوريات 1188-2492 . أُرشف من الأصل في 20 فبراير 2006. تم الاطلاع عليه في 4 يونيو 2019 . أُرشف بتاريخ 19 سبتمبر 2006 في أرشيف الإنترنت (Wayback Machine) .

تستند هذه المقالة جزئياً إلى ملف المصطلحات ، وهو متاح للعموم.

[ESR_1996_Dict-1] ريموند، إريك ستيفن (1996). قاموس المخترق الجديد . مطبعة معهد ماساتشوستس للتكنولوجيا . الصفحات 378-379 . ISBN 978-0-26268092-9مقدمة من منظور المخترقين ، والتي تُدرج عادةً في الدليل الرئيسي لتوزيعة مصدر يونكس، تحتوي على مؤشر إلى وثائق أكثر تفصيلاً، ومعلومات عن المساهمين، وسجل المراجعات المتنوعة، والملاحظات، وما إلى ذلك. [...] عندما يُسألون، يربط المخترقون دائمًا اتفاقية README بالمشهد الشهير في مغامرات أليس في بلاد العجائب للويس كارول، حيث تواجه أليس وجبات خفيفة سحرية تحمل اسمي "كلني" و"اشربني".

[Manes_1996-2] 1 2 مانس، ستيفن (نوفمبر 1996). "اقرأني؟ بالتأكيد - قبل أن أشتري!". عالم الكمبيوتر الشخصي . 14 (11): 366.

[Decus_1974_readme-3] "أرشيف PDP-10: decus/20-0079/readme.txt من decus_20tap3_198111" . pdp-10.trailing-edge.com . 27-11-1974 . تم الاسترجاع في 3-03-2018 . [README.TXT هو ملف DOC الخاص ببرامج SPICE/SINC/SLIC]. يحتوي هذا الشريط الاحتياطي على برامج تحليل الدوائر SPICE SINC وSLIC الموصوفة في نشرة برامج التطبيقات، المجلد 4. المتطلبات: يتطلب برنامج SPICE لغة FORTRAN-10 الإصدار 4 نظرًا لاستخدامه بيانات هوليريث المعدلة لليمين. يستغرق تنفيذه حوالي 47 كيلوبايت. [...] يتضمن أيضًا هذا الملف، وملفات FOROTS المصاحبة لملفات SAVes، ومصدر برنامج SECOND.MAC، وهو روتين التوقيت. ينقسم برنامج SPICE إلى ثلاثة أجزاء: 1SPICE.FOR، 2 و3. يوجد مستند مطبوع يشرح كل برنامج منها، وهو مُضمّن في حزمة DECUS. طُوّرت الوثائق والبرامج في الأصل من قِبل قسم الهندسة الكهربائية بجامعة كاليفورنيا في بيركلي على جهاز CDC 6400. باستثناء تحويل لغة FORTRAN إلى نظام DECsystem-10، لم تُجرَ أي تغييرات على البرامج. بالنسبة لبيانات الاختبار، أظهر برنامجا SLIC وSINC اختلافًا طفيفًا مقارنةً بجهاز 6400، بينما لم يُظهر برنامج SPICE أي اختلاف. بالتوفيق! آشلي غرايسون، 27 نوفمبر 1974 [نهاية ملف README.TXT]

[Decus_1975_readme-4] "DECUS 10-LIB-4 يحتوي على الملفات من 10-210 إلى 10-241، باستثناء الملف 10-223" . pdp-10.trailing-edge.com . 27-03-1975 . تاريخ الاسترجاع: 03-03-2018 . تُشكّل الملفات الموجودة على شريط FAILSAFE هذا نظام UCI LISP. وهي موثقة في معظمها في دليل UCI LISP، المتوفر من قسم علوم المعلومات والحاسوب في جامعة كاليفورنيا، إرفاين، كاليفورنيا.

[PWB_1977-5] "Programmer's Workbench /sys/source/lex/README" . يوليو 1977. تم الاطلاع عليه بتاريخ 25 يناير 2020 .

[UNIX7_1979-6] "Unix الإصدار السابع /usr/doc/README" . 1979. تم الاطلاع عليه بتاريخ 25-01-2020 .

[BSD_1980-7] "أول ملف README لنظام BSD 32 بت usr/doc/" . مارس 1980. تم الاطلاع عليه بتاريخ 25 يناير 2020 .

[Langemeier_2011-8] لانغماير، جيف (29 يوليو 2011). "رد: أصل ملف README" . تم الاطلاع عليه بتاريخ 25 يناير 2020 عبر Stackexchange. [...] كان لديهم ملفات README (ملفات مطبوعة فعلية) لجميع بطاقات التثقيب وأشرطة التسجيل المغناطيسية، وأي شيء آخر يُعتبر "برنامجًا". في ذلك الوقت، كان وجود ملف README ضروريًا نظرًا للعملية الشاقة التي كانت تتطلبها عملية إنشاء البرنامج وتشغيله وكل ما يتعلق به. تضمنت ملفات README هذه أحيانًا أيضًا مطبوعات توضح كيفية تثقيب بطاقات التثقيب كشكل من أشكال التحقق من الأخطاء وتصحيحها. يبدو أن هذا النظام يتبع النظام القديم أيضًا، حيث كان يتم إرفاق "حزمة" من الورق مع كل بطاقة تثقيب، مطبوع عليها عبارة README بأحرف كبيرة، والتي كانت تحتوي على جميع تعليمات استخدام بطاقات التثقيب وتحميلها في النظام. للمقارنة الزمنية، كان ذلك في الستينيات. [...]

[Abdelhafith_2015-9] عبد الحفيظ، عمر (13 أغسطس 2015). "README.md: التاريخ والمكونات" . تم الاطلاع عليه بتاريخ 25 يناير 2020 .{{cite web}}: CS1 maint: deprecated archiveal service ( link )

[GNU_Standards-10] "معايير ترميز جنو: الإصدارات" . www.gnu.org . تم الاطلاع عليه بتاريخ 2018-03-03 .

[11] "حول ملفات README" . وثائق GitHub . تم الاطلاع عليه بتاريخ 31-05-2024 .

[Github_2014_Markup-12] "الترميز" . جيت هاب . 25-12-2014 . تم الاسترجاع في 8-02-2015 .

[13] برانا، جيدي أرثا أزريادي؛ ترويدي، كريستوف؛ ثونغ، فرديان؛ أتاباتو، ثوشاري؛ لو، ديفيد (2019-06-01). "تصنيف محتوى ملفات README على GitHub" . هندسة البرمجيات التجريبية . 24 (3): 1296-1327 . arXiv : 1802.06997 . doi : 10.1007/s10664-018-9660-3 . ISSN 1573-7616 .

[ 1 ]

[ 2 ]

[ 3 ]

[ 4 ]

[ 5 ]

[ 6 ]

[ 7 ]

[ 8 ]

[ 9 ]

[ 10 ]

[

[

[ 13 ]

اللغة	العربية (RTL)
روابط موسوعية	30 رابطاً
المصدر الأصلي	ويكيبيديا ↗

محتوى

تاريخ

متعلق ب

انظر أيضاً

مراجع

للمزيد من القراءة