Lesson 21 / الدرس 21

Forks: contributing to work that is not yours / الـforks: الإسهام في عمل ليس لك

You cannot push to a repository you do not have write access to — which is almost all of them. A fork is your own copy on GitHub, and it is how every outside contribution is made.

لا تستطيع الدفع إلى مستودع لا تملك حق الكتابة فيه — وهي كلها تقريبًا. والـfork نسختك أنت على GitHub، وبه يُقدَّم كل إسهام خارجي.

Everything so far assumed the repository was yours. Now consider the other case: you find a genuine bug in a project you use, or a mistake in its documentation, and you want to fix it. You have no write access, so git push is refused. A fork is your own copy of their repository, on your own account, which you can push to freely.

كل ما سبق افترض أن المستودع لك. والآن انظر في الحالة الأخرى: تجد عيبًا حقيقيًا في مشروع تستخدمه، أو خطأً في توثيقه، وتريد إصلاحه. ولا حق كتابة لك، فيُرفض git push. والنسخة المستقلة (fork) هي نسختك أنت من مستودعهم، على حسابك أنت، وتستطيع الدفع إليها بحرية.

1. Fork on GitHub                 their repo -> your account
2. git clone git@github.com:you/their-project.git
3. git switch -c fix-typo-in-readme
4.    ... make the change, commit ...
5. git push -u origin fix-typo-in-readme
6. Open a pull request — FROM your fork's branch, TO their main

Six steps, and only the first and last are new. Steps 2 to 5 are lessons 12, 18 and 19 exactly as you already know them. Run the demonstration for the picture of who owns what.

Keeping a fork up to date

A fork is a copy taken at one moment; it does not follow the original. Weeks later theirs has moved on and yours has not, and a pull request built on a stale base is harder to merge. The fix is a second remote, conventionally called upstream, pointing at the original.

والـfork نسخة أُخذت في لحظة؛ ولا يتبع الأصل. فبعد أسابيع يكون مستودعهم قد تحرك ومستودعك لا، والـpull request المبني على أساس قديم أصعب دمجًا. والإصلاح remote ثانٍ، يسمى عرفًا upstream، يشير إلى الأصل.

git remote add upstream git@github.com:their-org/project.git
git remote -v                     now you have two

git switch main
git fetch upstream
git merge upstream/main           bring their newer work into your main
git push                          and update your fork on GitHub

Do this before starting any new piece of work on a fork. origin stays your copy and upstream is theirs — a naming convention, not a rule, but one everyone follows.

افعل هذا قبل بدء أي قطعة عمل جديدة على fork. ويبقى origin نسختك وupstream نسختهم — وهو عرف تسمية لا قاعدة، لكنه عرف يتبعه الجميع.

Contributing to a project well

Before you write anything	Why
Read CONTRIBUTING.md	Most projects say exactly how they want changes
Check the open issues	Someone may already be working on it
Open an issue first, for anything large	They may not want the change at all
Match the existing style	A change that looks foreign is harder to accept
One change per pull request	Lesson 19 — a big one gets a shallow review

The third row saves the most time. Writing a large feature and then discovering the maintainers did not want it is a genuinely common and demoralising experience, and one short question beforehand avoids it entirely.

ولا تفتح أبدًا pull request من main في fork خاصتك. فهو يعمل، ثم يوقعك: إذ لا تستطيع وهو مفتوح تحديث main من upstream دون إضافة تلك الـcommits إلى الطلب، ولا تستطيع بدء إسهام ثانٍ دون أن تشابكه بالأول. ففرّع دائمًا. وهذا هو السبب العملي لإصرار الدورة كلها عليه، وهو الخطأ الأشيع عند المسهمين لأول مرة.

A first contribution does not have to be code. A typo in the documentation, a broken link, an unclear error message, a missing example — all of these are real contributions, all are welcome in most projects, and all take you through the entire process once with almost no risk of being wrong. Doing that once is worth more than reading about it ten times.

في VS Code: تستطيع إضافة GitHub عمل fork وclone في خطوة واحدة من لوحة الأوامر، ويسرد عرض Pull Requests قضايا المشروع المفتوحة فتجد ما تعمل عليه دون مغادرة المحرر. لكنها لا تضيف upstream عنك — وذلك ما يزال يستحق الفعل باليد.

Try it live / جرّب بنفسك

<h1>Contributing to someone else's project</h1>
<p>The project: …</p>

<h2>My two remotes</h2>
<pre class="term">$ git remote -v
origin    … (fetch)
upstream  … (fetch)</pre>

<h2>Staying up to date</h2>
<pre class="term">$ git fetch upstream
$ git merge upstream/main
…</pre>

<h2>My change</h2>
<pre class="term">$ git switch -c …
$ git commit -m "…"
…</pre>

<h2>What CONTRIBUTING asked for</h2>
<p>…</p>

<style>
    .term { background: #0f172a; color: #e2e8f0; padding: 1rem;
            border-radius: .5rem; overflow-x: auto; }
</style>

Preview / المعاينة

Check yourself / اختبر نفسك

1. Why do you need a fork to contribute to someone else's project?

2. What is the upstream remote?

ما هو remote الـupstream؟

3. Why should a contribution never come from your fork's main?

لماذا لا ينبغي أن يأتي الإسهام من main في fork خاصتك؟

Your task / مهمتك

Fork a real public repository — something small you actually use, or one of the many projects that keep a "good first issue" list. Set up upstream, branch, and prepare a genuine small improvement: a typo, a broken link, a clearer sentence in the documentation. Whether you open the pull request is up to you; report the fork, the two remotes, the branch and the change, and say what the project's CONTRIBUTING file asked of you.

اعمل fork لمستودع عام حقيقي — شيء صغير تستخدمه فعلًا، أو أحد المشاريع الكثيرة التي تحتفظ بقائمة "good first issue". وجهّز upstream، وفرّع، وأعدّ تحسينًا صغيرًا حقيقيًا: خطأ مطبعي، أو رابط مكسور، أو جملة أوضح في التوثيق. وفتح الـpull request أمر يعود إليك؛ وأبلغ عن الـfork والـremoteين والـbranch والتغيير، وقل ما الذي طلبه منك ملف CONTRIBUTING في المشروع.

A real fork of a real project fork حقيقي لمشروع حقيقي
git remote -v showing origin AND upstream git remote -v يُظهر origin وupstream
A branch, not main branch لا main
What CONTRIBUTING.md asked for ما طلبه CONTRIBUTING.md