docs/patchwork

   1
   2         Patchwork with Link
   3
   4 This document will cover everything from actually working inside
   5 the Link codebase to creating patches and sending them.
   6
   7 1. FIGURING OUT WHAT TO DO
   8
   9         The best way to find something to work on in the source
  10         is to ask around in the mailing list, or look at the TODO
  11         files. You can also just adjust code to follow the coding
  12         styles.
  13
  14 2a. SETTING UP YOUR ENVIRONMENT (GIT)
  15
  16         Once you've found something to do, you can either work
  17         via Git by cloning the official repository:
  18
  19                 $ git clone https://github.com/n11software/link.git
  20
  21         and basing your work off of the last release by creating
  22         a new branch and basing it off of the last release:
  23
  24                 $ git checkout -b devel tags/v1.0.1
  25
  26         You can update the master branch and devel branch by:
  27
  28                 $ git checkout master && git pull origin master
  29                 $ git checkout devel && git merge --no-ff master
  30
  31 2b. SETTING UP YOUR ENVIRONMENT (TARBALLS)
  32
  33         Once you've found something to do, you can use tarballs
  34         to do your work by grabbing the source tarballs from the
  35         GitHub release.
  36
  37         Usually, you will end up editing multiple files (if not,
  38         skip this section) so you should extract the tarball into
  39         two separate folders; one for development and the other
  40         as a vanilla tree so we can use it to compare against.
  41
  42                 $ gzip -cd link-1.0.1.tar.gz | tar xvf
  43                 $ mv link-1.0.1 link-devel
  44                 $ gzip -cd link-1.0.1.tar.gz | tar xvf
  45                 $ mv link-1.0.1 link-vanilla
  46
  47         To update the folders upon a new version release, you'll
  48         need to delete the old link-devel folder and get the
  49         patch file from GitHub (which will be named like:
  50         patch-1.0.1) and apply it to link-vanilla like so:
  51
  52                 $ rm -rf link-devel
  53                 $ cd link-vanilla && patch -p1 -ipatch-1.0.1
  54                 $ cd ../ && cp -r link-vanilla/ link-devel/
  55
  56         If you only need to modify a single file, just do:
  57
  58                 $ cp $MYFILE $MYFILE.orig
  59                 $ vi $MYFILE
  60
  61 3a. Making a commit (GIT)
  62
  63         Once you've made your changes, if you use GIT, you first
  64         need to create a commit like so:
  65
  66                 $ git add <file name or .> && git commit -s
  67
  68         You may need to add your name and email to your gitconfig
  69
  70                 $ git config --global user.name "John Doe"
  71                 $ git config --global user.email "johnd@n11.dev"
  72
  73         The canonical commit name format is:
  74
  75                 <subsys>: <commit name>
  76
  77 3b. Making the patch files
  78
  79         Once you have made your commit (GIT), or have made your
  80         changes (TARBALLS), you are able to make the patch files.
  81
  82         For GIT users, you can simply do:
  83
  84                 $ git format-patch <commit ID>
  85
  86         where <commit ID> is the commit ID of the commit before
  87         your first commit.
  88
  89         For people using TARBALLS, there is more steps depending
  90         on your change.
  91
  92         If you have only edited a single file and created the
  93         .orig copy, you can just do:
  94
  95                 $ diff -up $MYFILE{.orig,} > patch
  96
  97         If you did multiple files and you have the vanilla source
  98         tree, you need to do:
  99
 100                 $ diff -uprN link-vanilla link-devel > link-devel/patch
 101
 102 3c. Editing the patch files (TARBALLS)
 103
 104         When using TARBALLS, you will have to modify your patch
 105         files to work correctly with the patch format that git
 106         uses.
 107
 108         To edit it correctly, all you need to add to the top of
 109         your patch file is something like:
 110
 111                 From: John Doe <johnd@n11.dev>
 112                 Date: Sun, 19 Mar 2023 19:51:52 -0400
 113                 Subject: [PATCH] <commit name>
 114
 115                 <commit description>
 116
 117                 Signed-off-by: John Dode <johnd@n11.dev>
 118                 ---
 119
 120                 <diff here>
 121
 122 4. Send the patch to the mailing list
 123
 124         You can use 'git send-email' to send your patches to the
 125         mailing list. For example:
 126
 127         git send-email --to=~aristonl/link-devel@lists.sr.ht patches/commit.patch
 128
 129         You will have to configure your '~/.gitconfig' to work with your email
 130         provider. Navigate to https://git-send-email.io for more information.
 131
 132         You can optionally use mutt/neomutt to send your patch like so:
 133
 134         mutt -H patches/commit.patch
 135