From 9e035c914dd1623acc0472e98eb57180cfc0327b Mon Sep 17 00:00:00 2001
From: Ingolf Wagner <contact@ingolf-wagner.de>
Date: Fri, 3 Jan 2020 15:57:52 +1300
Subject: [PATCH] doc/submitting-changes : improved section 15.1

---
 doc/contributing/submitting-changes.xml | 63 +++++++------------------
 1 file changed, 16 insertions(+), 47 deletions(-)

diff --git a/doc/contributing/submitting-changes.xml b/doc/contributing/submitting-changes.xml
index f283ae1e6851..73222c1a49ac 100644
--- a/doc/contributing/submitting-changes.xml
+++ b/doc/contributing/submitting-changes.xml
@@ -13,7 +13,7 @@
    </listitem>
    <listitem>
     <para>
-     Fork the repository on GitHub.
+     Fork <link xlink:href="https://github.com/nixos/nixpkgs/">the Nixpkgs repository</link> on GitHub.
     </para>
    </listitem>
    <listitem>
@@ -22,15 +22,10 @@
      <itemizedlist>
       <listitem>
        <para>
-        You can make branch from a commit of your local <command>nixos-version</command>. That will help you to avoid additional local compilations. Because you will receive packages from binary cache.
-        <itemizedlist>
-         <listitem>
-          <para>
-           For example: <command>nixos-version</command> returns <command>15.05.git.0998212 (Dingo)</command>. So you can do:
-          </para>
-         </listitem>
-        </itemizedlist>
+        You can make branch from a commit of your local <command>nixos-version</command>. That will help you to avoid additional local compilations. Because you will receive packages from binary cache. For example
 <screen>
+<prompt>$ </prompt>nixos-version --hash
+0998212
 <prompt>$ </prompt>git checkout 0998212
 <prompt>$ </prompt>git checkout -b 'fix/pkg-name-update'
 </screen>
@@ -47,13 +42,11 @@
    <listitem>
     <para>
      Make commits of logical units.
-     <itemizedlist>
-      <listitem>
-       <para>
-        If you removed pkgs, made some major NixOS changes etc., write about them in <command>nixos/doc/manual/release-notes/rl-unstable.xml</command>.
-       </para>
-      </listitem>
-     </itemizedlist>
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+     If you removed pkgs or made some major NixOS changes, write about it in the release notes for the next stable release. For example <command>nixos/doc/manual/release-notes/rl-2003.xml</command>.
     </para>
    </listitem>
    <listitem>
@@ -178,7 +171,7 @@ Additional information.
    </listitem>
    <listitem>
     <para>
-     Rebase you branch against current <command>master</command>.
+     <link xlink:href="https://git-scm.com/book/en/v2/Git-Branching-Rebasing">Rebase</link> your branch against current <command>master</command>.
     </para>
    </listitem>
   </itemizedlist>
@@ -194,36 +187,12 @@ Additional information.
    </listitem>
    <listitem>
     <para>
-     Create pull request:
-     <itemizedlist>
-      <listitem>
-       <para>
-        Write the title in format <command>(pkg-name | nixos/&lt;module>): improvement</command>.
-        <itemizedlist>
-         <listitem>
-          <para>
-           If you update the pkg, write versions <command>from -> to</command>.
-          </para>
-         </listitem>
-        </itemizedlist>
-       </para>
-      </listitem>
-      <listitem>
-       <para>
-        Write in comment if you have tested your patch. Do not rely much on <command>TravisCI</command>.
-       </para>
-      </listitem>
-      <listitem>
-       <para>
-        If you make an improvement, write about your motivation.
-       </para>
-      </listitem>
-      <listitem>
-       <para>
-        Notify maintainers of the package. For example add to the message: <command>cc @jagajaga @domenkozar</command>.
-       </para>
-      </listitem>
-     </itemizedlist>
+     Create the pull request
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+     Follow <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/.github/CONTRIBUTING.md#submitting-changes">the contribution guidelines</link>.
     </para>
    </listitem>
   </itemizedlist>