1 00:00:04,960 --> 00:00:19,999 [Music] 2 00:00:22,720 --> 00:00:26,599 good morning everyone my name is Jay and 3 00:00:25,439 --> 00:00:28,880 I'm going to be the session chair for 4 00:00:26,599 --> 00:00:31,599 this morning and we've got a great talk 5 00:00:28,880 --> 00:00:34,520 coming up we have ten lenberg who's an 6 00:00:31,599 --> 00:00:36,280 experienced data science scientist and a 7 00:00:34,520 --> 00:00:38,120 developer of the scores open source 8 00:00:36,280 --> 00:00:39,440 project and he's here to talk to us 9 00:00:38,120 --> 00:00:41,039 about Lessons Learned From developing 10 00:00:39,440 --> 00:00:43,600 that open source project please welcome 11 00:00:41,039 --> 00:00:43,600 Tennessee to the 12 00:00:45,760 --> 00:00:51,640 stage yeah thank you very much uh people 13 00:00:49,399 --> 00:00:53,800 all morning have been kindly asking me 14 00:00:51,640 --> 00:00:55,840 if I'm ready to give my talk or not and 15 00:00:53,800 --> 00:00:58,440 I have to say the answer is no not 16 00:00:55,840 --> 00:01:00,000 really and the reason for that is like I 17 00:00:58,440 --> 00:01:01,800 think I've got a good deck and a good 18 00:01:00,000 --> 00:01:03,680 content and lots of good information but 19 00:01:01,800 --> 00:01:05,519 I've been struggling to find like what's 20 00:01:03,680 --> 00:01:07,240 the story what's the narrative spine you 21 00:01:05,519 --> 00:01:09,119 know where's the kind of hero hero's 22 00:01:07,240 --> 00:01:11,320 journey what's the three act structure 23 00:01:09,119 --> 00:01:12,720 or the the five room encounter that 24 00:01:11,320 --> 00:01:14,560 we're going to build out of this and the 25 00:01:12,720 --> 00:01:17,159 reality is that making an open source 26 00:01:14,560 --> 00:01:19,799 package isn't really like that it's just 27 00:01:17,159 --> 00:01:22,880 a whole lot of stuff and and a lot of 28 00:01:19,799 --> 00:01:25,439 this talk is just a whole lot of stuff 29 00:01:22,880 --> 00:01:27,720 and like the reason I made this talk is 30 00:01:25,439 --> 00:01:30,600 that I've got 20 years of development 31 00:01:27,720 --> 00:01:33,360 experience working with python and and 32 00:01:30,600 --> 00:01:35,000 like it was hard you know with all that 33 00:01:33,360 --> 00:01:36,560 experience it was you know pretty 34 00:01:35,000 --> 00:01:38,159 difficult to you know find out all the 35 00:01:36,560 --> 00:01:40,600 information and make all the choices and 36 00:01:38,159 --> 00:01:42,840 figure out how to put it together and 37 00:01:40,600 --> 00:01:44,719 the story of of what was involved was 38 00:01:42,840 --> 00:01:46,880 just dealing with a whole lot of stuff 39 00:01:44,719 --> 00:01:48,560 so uh you know the talk this sometimes I 40 00:01:46,880 --> 00:01:50,000 give funny talks this isn't a 41 00:01:48,560 --> 00:01:52,600 particularly funny talk at least you 42 00:01:50,000 --> 00:01:53,840 know not deliberately um and we're just 43 00:01:52,600 --> 00:01:56,200 going to go through the Journey of all 44 00:01:53,840 --> 00:01:58,280 of the things that you might need to to 45 00:01:56,200 --> 00:02:00,159 you know tackle and deal with and the 46 00:01:58,280 --> 00:02:01,799 slides are pretty dense that's cuz I 47 00:02:00,159 --> 00:02:03,640 want there to be like a you know like a 48 00:02:01,799 --> 00:02:05,520 good record and a good set of content 49 00:02:03,640 --> 00:02:07,960 and things can people take photos of or 50 00:02:05,520 --> 00:02:10,080 pause the video on I'll try to talk 51 00:02:07,960 --> 00:02:11,680 separately from what's on the slide I'll 52 00:02:10,080 --> 00:02:13,680 I'll attend to the general theme I'll 53 00:02:11,680 --> 00:02:15,519 call out a few stories and a few few 54 00:02:13,680 --> 00:02:17,560 points we went through um but if there's 55 00:02:15,519 --> 00:02:18,879 sort of you know a lot up there or I'm 56 00:02:17,560 --> 00:02:20,440 not addressing all of the points you 57 00:02:18,879 --> 00:02:22,440 know fire them up if we've got time for 58 00:02:20,440 --> 00:02:25,760 questions or you know drop them in the 59 00:02:22,440 --> 00:02:27,160 chat and the other reason I'm not ready 60 00:02:25,760 --> 00:02:29,440 is that I don't think that I'm really 61 00:02:27,160 --> 00:02:30,879 terribly much more qualified than huge 62 00:02:29,440 --> 00:02:32,360 numbers of people in this room 63 00:02:30,879 --> 00:02:34,640 particularly and it sort of slowly 64 00:02:32,360 --> 00:02:36,360 dawned on me that I'll be presenting my 65 00:02:34,640 --> 00:02:38,239 own sort of experience and the 66 00:02:36,360 --> 00:02:40,200 experience of my team and building and 67 00:02:38,239 --> 00:02:42,400 constructing this package to a room full 68 00:02:40,200 --> 00:02:44,400 of people who may well have known better 69 00:02:42,400 --> 00:02:45,680 than we did uh how to make those steps 70 00:02:44,400 --> 00:02:47,680 along the way a lot of these lessons 71 00:02:45,680 --> 00:02:49,640 will learned the hard way as I went and 72 00:02:47,680 --> 00:02:51,239 no doubt there are few surprises 73 00:02:49,640 --> 00:02:53,920 remaining waiting for me 74 00:02:51,239 --> 00:02:56,480 too so a few things that aren't C 75 00:02:53,920 --> 00:02:58,319 covered number one naming your package 76 00:02:56,480 --> 00:03:01,400 if anyone's figured out how please let 77 00:02:58,319 --> 00:03:03,840 me know uh legal advice I'm not 78 00:03:01,400 --> 00:03:05,599 qualified you'll need to find your own 79 00:03:03,840 --> 00:03:08,159 own course through uh through legal 80 00:03:05,599 --> 00:03:10,959 advice like choosing a license Dido 81 00:03:08,159 --> 00:03:12,879 approval processes wherever you find 82 00:03:10,959 --> 00:03:14,840 yourself you may find approval processes 83 00:03:12,879 --> 00:03:16,760 are part of your life they're up to you 84 00:03:14,840 --> 00:03:19,560 and I'm definitely going to T not touch 85 00:03:16,760 --> 00:03:21,720 the choice of a text 86 00:03:19,560 --> 00:03:24,080 editor I think it's always helpful to 87 00:03:21,720 --> 00:03:26,239 start with one thing to take away if 88 00:03:24,080 --> 00:03:28,480 you're going to take away one thing 89 00:03:26,239 --> 00:03:31,640 these are good places to 90 00:03:28,480 --> 00:03:34,640 start I I had found them before I 91 00:03:31,640 --> 00:03:37,959 started I did not find them before I 92 00:03:34,640 --> 00:03:40,080 started I did find package manager 93 00:03:37,959 --> 00:03:42,319 thingo I don't know what these are 94 00:03:40,080 --> 00:03:44,120 called one of them is called hatch and 95 00:03:42,319 --> 00:03:45,680 it describes itself as an extensible 96 00:03:44,120 --> 00:03:48,720 python project 97 00:03:45,680 --> 00:03:51,720 manager that that sounds helpful and the 98 00:03:48,720 --> 00:03:54,280 other one claims to make it all easy 99 00:03:51,720 --> 00:03:56,200 which made me skeptical but it is a 100 00:03:54,280 --> 00:04:00,640 commonly adopted framework and both of 101 00:03:56,200 --> 00:04:03,360 these things do a lot of things see also 102 00:04:00,640 --> 00:04:05,120 many blog posts discussing which one is 103 00:04:03,360 --> 00:04:07,840 better which one is not better why you 104 00:04:05,120 --> 00:04:11,200 should adopt one when it's new when it's 105 00:04:07,840 --> 00:04:14,560 deprecated and yeah there's a lot of 106 00:04:11,200 --> 00:04:17,479 complexity uh we chose hatch in the end 107 00:04:14,560 --> 00:04:20,320 but we're really using only a tiny part 108 00:04:17,479 --> 00:04:22,479 of hatch um largely because all of the 109 00:04:20,320 --> 00:04:24,080 various sort of decisions it's made we 110 00:04:22,479 --> 00:04:26,400 wanted to be more kind of like mindful 111 00:04:24,080 --> 00:04:28,440 of so if I'm talking about me I'm 112 00:04:26,400 --> 00:04:30,600 talking about me if I'm talking about we 113 00:04:28,440 --> 00:04:33,560 I mean the develop velers of scores and 114 00:04:30,600 --> 00:04:35,560 the people who've made contributions um 115 00:04:33,560 --> 00:04:37,280 I may fall find myself falling into 116 00:04:35,560 --> 00:04:40,360 either sort of patent at various points 117 00:04:37,280 --> 00:04:42,440 along the time so both of these have you 118 00:04:40,360 --> 00:04:44,120 know more or less to do with a bunch of 119 00:04:42,440 --> 00:04:47,360 the rigging and infrastructure and 120 00:04:44,120 --> 00:04:50,000 processes that are involved in you know 121 00:04:47,360 --> 00:04:52,280 the activity of software development uh 122 00:04:50,000 --> 00:04:54,000 explaining it to the internet testing it 123 00:04:52,280 --> 00:04:57,320 assuring it going through release 124 00:04:54,000 --> 00:04:59,039 processes all those sorts of things um 125 00:04:57,320 --> 00:05:01,199 but there are also Choose Your Own 126 00:04:59,039 --> 00:05:04,240 Adventure versions of every single part 127 00:05:01,199 --> 00:05:05,880 of these as well and sometimes those 128 00:05:04,240 --> 00:05:07,440 Choose Your Own Adventure versions might 129 00:05:05,880 --> 00:05:09,240 be better documented or even a better 130 00:05:07,440 --> 00:05:12,039 choice for 131 00:05:09,240 --> 00:05:14,560 you okay so how to lay things out on 132 00:05:12,039 --> 00:05:17,600 disk this is one of those things that 133 00:05:14,560 --> 00:05:19,039 that's changed uh and become more mature 134 00:05:17,600 --> 00:05:21,199 but there are some undocumented 135 00:05:19,039 --> 00:05:23,440 weirdnesses to how to lay things out on 136 00:05:21,199 --> 00:05:25,440 disk that I don't see talked about as as 137 00:05:23,440 --> 00:05:28,240 much at least I didn't come across them 138 00:05:25,440 --> 00:05:30,759 so tldr definitely put your source code 139 00:05:28,240 --> 00:05:33,800 in a source folder and don't rely on the 140 00:05:30,759 --> 00:05:36,560 class path for finding your modules um 141 00:05:33,800 --> 00:05:39,560 do use an editable install and a virtual 142 00:05:36,560 --> 00:05:41,680 environment for doing your software 143 00:05:39,560 --> 00:05:44,520 development okay so here's how I lay 144 00:05:41,680 --> 00:05:46,199 things out on disk and you know this may 145 00:05:44,520 --> 00:05:48,000 seem like a dry topic like I said 146 00:05:46,199 --> 00:05:52,080 building an open source package is just 147 00:05:48,000 --> 00:05:53,880 a whole lot of stuff um you'll notice 148 00:05:52,080 --> 00:05:55,120 there are some files sitting at the top 149 00:05:53,880 --> 00:05:56,639 level that kind of look like 150 00:05:55,120 --> 00:06:00,039 documentation and there's a 151 00:05:56,639 --> 00:06:02,160 documentation folder uh that's largely 152 00:06:00,039 --> 00:06:04,759 because various other parts of the 153 00:06:02,160 --> 00:06:07,800 ecosystem just expect things to be in 154 00:06:04,759 --> 00:06:10,199 particular places and quite a lot of 155 00:06:07,800 --> 00:06:12,400 what we found out the hard way was like 156 00:06:10,199 --> 00:06:14,319 what things just have to be in some 157 00:06:12,400 --> 00:06:18,360 particular place or another for it to be 158 00:06:14,319 --> 00:06:21,400 found by for example GitHub or Google or 159 00:06:18,360 --> 00:06:23,759 the cicd package or you know various 160 00:06:21,400 --> 00:06:26,400 types of Integrations so the the 161 00:06:23,759 --> 00:06:28,440 integration ecosystem around open source 162 00:06:26,400 --> 00:06:30,720 packages has got a bit harder so I'm 163 00:06:28,440 --> 00:06:31,919 pretty happy you know so each time we 164 00:06:30,720 --> 00:06:34,000 kind of go through one of these things 165 00:06:31,919 --> 00:06:36,039 I'll comment on whether like we're happy 166 00:06:34,000 --> 00:06:37,680 with our choices in terms of whether 167 00:06:36,039 --> 00:06:40,639 this is going to apply to every package 168 00:06:37,680 --> 00:06:42,039 you know like probably not um but I 169 00:06:40,639 --> 00:06:44,440 think this is a reasonably sound 170 00:06:42,039 --> 00:06:44,440 starting 171 00:06:44,720 --> 00:06:52,440 point okay configuration files uh tldr 172 00:06:48,720 --> 00:06:56,360 do use P project. toml so more and more 173 00:06:52,440 --> 00:06:57,879 projects uh are using like P project or 174 00:06:56,360 --> 00:07:01,120 toml I think this is great please do 175 00:06:57,879 --> 00:07:02,680 more of it this would was one of those 176 00:07:01,120 --> 00:07:04,720 we went one way then the other way then 177 00:07:02,680 --> 00:07:07,840 the other way then the other way type 178 00:07:04,720 --> 00:07:11,199 scenarios for us like a lot of packages 179 00:07:07,840 --> 00:07:14,199 use dot files I come from a generation 180 00:07:11,199 --> 00:07:16,319 that used setup dop by default so I kind 181 00:07:14,199 --> 00:07:18,800 of started there before moving over to 182 00:07:16,319 --> 00:07:21,319 Pi project. toml so there were some 183 00:07:18,800 --> 00:07:23,080 Journeys sort of backwards and forwards 184 00:07:21,319 --> 00:07:25,680 like I didn't realize you don't need 185 00:07:23,080 --> 00:07:27,120 setup dopy anymore that was that was a 186 00:07:25,680 --> 00:07:29,039 discovery you don't need setup.py 187 00:07:27,120 --> 00:07:32,240 anymore and it it it seems to be better 188 00:07:29,039 --> 00:07:33,919 without it so uh I will comment that 189 00:07:32,240 --> 00:07:36,479 like with the dot file type 190 00:07:33,919 --> 00:07:40,080 configuration like your pilot RC and 191 00:07:36,479 --> 00:07:42,080 this RC and the other RC and cicd 192 00:07:40,080 --> 00:07:45,479 subfolders full of stuff that tells your 193 00:07:42,080 --> 00:07:47,680 cicd what to do I feel like that's just 194 00:07:45,479 --> 00:07:49,639 hiding stuff and it's it's like a 195 00:07:47,680 --> 00:07:51,599 contradiction like you it's in your 196 00:07:49,639 --> 00:07:53,800 package but you want to hide it so it's 197 00:07:51,599 --> 00:07:56,120 not cluttering things and being 198 00:07:53,800 --> 00:07:57,800 distracting but your developers need to 199 00:07:56,120 --> 00:08:00,520 know it's there because it's how it all 200 00:07:57,800 --> 00:08:01,879 actually works so I feel like you know 201 00:08:00,520 --> 00:08:04,280 that's something I feel like isn't maybe 202 00:08:01,879 --> 00:08:07,560 sort of sold perfectly 203 00:08:04,280 --> 00:08:10,319 yet versioning oh boy did I get this one 204 00:08:07,560 --> 00:08:12,319 wrong so I thought versioning was just 205 00:08:10,319 --> 00:08:14,360 you know it was just kind of chill you 206 00:08:12,319 --> 00:08:15,759 know particularly in the early days of 207 00:08:14,360 --> 00:08:17,879 starting a package I thought it was just 208 00:08:15,759 --> 00:08:20,240 all cool so I kind of you know I made 209 00:08:17,879 --> 00:08:22,599 the numbers go like generally speaking 210 00:08:20,240 --> 00:08:24,319 up but I oscillated on whether to put a 211 00:08:22,599 --> 00:08:26,159 v in front of the version numbers for a 212 00:08:24,319 --> 00:08:28,240 little while and I started with a V and 213 00:08:26,159 --> 00:08:30,280 then I pulled off the V and that 214 00:08:28,240 --> 00:08:32,519 confused the heck out of the internet 215 00:08:30,280 --> 00:08:34,000 that that was really not a good call and 216 00:08:32,519 --> 00:08:35,800 I also didn't think it like mattered 217 00:08:34,000 --> 00:08:38,360 whether you had the like you know I just 218 00:08:35,800 --> 00:08:40,760 went with like 0.1 2.3.4 I didn't 219 00:08:38,360 --> 00:08:44,760 realize you needed the patch part of the 220 00:08:40,760 --> 00:08:47,240 version number to to kind of comply but 221 00:08:44,760 --> 00:08:48,720 you really need that third one and I 222 00:08:47,240 --> 00:08:51,040 think it played into a bunch of things 223 00:08:48,720 --> 00:08:53,399 in our early experience like search 224 00:08:51,040 --> 00:08:55,279 engines didn't find us or our updates 225 00:08:53,399 --> 00:08:57,959 for a really long time and it was 226 00:08:55,279 --> 00:09:00,120 incredibly confusing to understand why 227 00:08:57,959 --> 00:09:02,560 so even at the outset 228 00:09:00,120 --> 00:09:05,240 it was pretty important to use a really 229 00:09:02,560 --> 00:09:06,079 recognized convention for this and I 230 00:09:05,240 --> 00:09:09,440 didn't 231 00:09:06,079 --> 00:09:11,880 realize uh and the the ecosystem plays 232 00:09:09,440 --> 00:09:16,079 really well with semantic versioning it 233 00:09:11,880 --> 00:09:19,680 plays much less well with Calver and uh 234 00:09:16,079 --> 00:09:23,000 it plays mediumish with a new one called 235 00:09:19,680 --> 00:09:25,040 f and it doesn't play very well at all 236 00:09:23,000 --> 00:09:26,800 with just whatever someone felt like 237 00:09:25,040 --> 00:09:30,519 that morning you have to be fairly 238 00:09:26,800 --> 00:09:33,160 specific about it um so yeah that was a 239 00:09:30,519 --> 00:09:35,800 surprisingly important thing uh we went 240 00:09:33,160 --> 00:09:37,839 to version one we sort of to you know 241 00:09:35,800 --> 00:09:39,800 tossed up that change like there's a lot 242 00:09:37,839 --> 00:09:41,760 of articles about what going to version 243 00:09:39,800 --> 00:09:43,040 one means it seems to mean a lot of 244 00:09:41,760 --> 00:09:45,680 different things to a lot of different 245 00:09:43,040 --> 00:09:48,360 people python packages seem to like 246 00:09:45,680 --> 00:09:49,839 cruise on you know like low version 247 00:09:48,360 --> 00:09:52,079 numbers to quite a high level of 248 00:09:49,839 --> 00:09:56,360 maturity for a while it's not amazingly 249 00:09:52,079 --> 00:09:58,560 clear to me why um we just went for it 250 00:09:56,360 --> 00:10:00,279 so we we did go for it when it was ready 251 00:09:58,560 --> 00:10:01,920 so when I say we went for it we didn't 252 00:10:00,279 --> 00:10:04,200 just go for it we carefully approached 253 00:10:01,920 --> 00:10:06,440 it and then mindfully decided to do it 254 00:10:04,200 --> 00:10:09,000 but we didn't fear it and I think that 255 00:10:06,440 --> 00:10:11,720 was a good call uh really at the Crux of 256 00:10:09,000 --> 00:10:14,200 the sver system is information about 257 00:10:11,720 --> 00:10:16,839 what what's a fix and what's a bug and 258 00:10:14,200 --> 00:10:18,720 what breaks things backwards and that's 259 00:10:16,839 --> 00:10:23,079 kind of what the integration needs to 260 00:10:18,720 --> 00:10:24,760 know uh and it is better to provide that 261 00:10:23,079 --> 00:10:27,079 information if you can and it hasn't 262 00:10:24,760 --> 00:10:27,079 been a 263 00:10:27,360 --> 00:10:31,720 problem right branching there are a lot 264 00:10:29,800 --> 00:10:34,600 of different branching strategies out 265 00:10:31,720 --> 00:10:37,880 there um yeah this is something where 266 00:10:34,600 --> 00:10:39,440 like there's a tradeoff okay so like 267 00:10:37,880 --> 00:10:42,079 what we do is we have tags for each 268 00:10:39,440 --> 00:10:44,120 release it's pretty standard we put our 269 00:10:42,079 --> 00:10:46,920 development on develop not on Main which 270 00:10:44,120 --> 00:10:49,160 is like semi-standard we merge domain 271 00:10:46,920 --> 00:10:50,320 just before creating each release kind 272 00:10:49,160 --> 00:10:52,560 of 273 00:10:50,320 --> 00:10:54,880 semi-standard uh but it means like 274 00:10:52,560 --> 00:10:57,320 there's this kind of contention between 275 00:10:54,880 --> 00:10:59,600 like when you go to GitHub you see the 276 00:10:57,320 --> 00:11:01,639 default branch which is our develop 277 00:10:59,600 --> 00:11:04,040 Branch but when you go to read the docs 278 00:11:01,639 --> 00:11:06,240 you see the latest release and so they 279 00:11:04,040 --> 00:11:07,959 could be different and I'm not really 280 00:11:06,240 --> 00:11:10,320 happy that they're different and there 281 00:11:07,959 --> 00:11:13,160 doesn't seem to be a way to resolve that 282 00:11:10,320 --> 00:11:14,959 so this was also something we changed 283 00:11:13,160 --> 00:11:16,240 partway through our branching strategy 284 00:11:14,959 --> 00:11:19,160 like which one was developed and which 285 00:11:16,240 --> 00:11:21,760 one was main the change didn't make many 286 00:11:19,160 --> 00:11:23,839 big problems um but it's probably better 287 00:11:21,760 --> 00:11:26,399 to be stable up front because I think it 288 00:11:23,839 --> 00:11:28,560 did result again in compounding that 289 00:11:26,399 --> 00:11:29,880 like searchability of the documentation 290 00:11:28,560 --> 00:11:32,600 site issue 291 00:11:29,880 --> 00:11:35,480 that I referred to before so it it 292 00:11:32,600 --> 00:11:37,279 confused it confused the Bots until I 293 00:11:35,480 --> 00:11:39,639 had until the documentation was 294 00:11:37,279 --> 00:11:42,120 configured really nicely and it really 295 00:11:39,639 --> 00:11:44,200 it it got happy when we did the tagged 296 00:11:42,120 --> 00:11:46,160 releases it got happier when we went 297 00:11:44,200 --> 00:11:48,519 past version one it was like that like 298 00:11:46,160 --> 00:11:50,600 the search engines were less happy pre 299 00:11:48,519 --> 00:11:53,040 version one and then once we started 300 00:11:50,600 --> 00:11:55,079 using sort of sver properly then it 301 00:11:53,040 --> 00:11:57,079 started to understand how the versions 302 00:11:55,079 --> 00:11:58,680 of our documentation site like hung 303 00:11:57,079 --> 00:12:00,600 together and direct people to the right 304 00:11:58,680 --> 00:12:02,720 one and things like that so there was 305 00:12:00,600 --> 00:12:05,320 sort of these unexpected links between 306 00:12:02,720 --> 00:12:06,839 things like branching strategy and 307 00:12:05,320 --> 00:12:08,639 whether when we told someone about our 308 00:12:06,839 --> 00:12:10,120 package they could find it so there were 309 00:12:08,639 --> 00:12:12,120 these sort of like connections at a 310 00:12:10,120 --> 00:12:14,639 distance that that you know as far as I 311 00:12:12,120 --> 00:12:18,560 knew weren't written down 312 00:12:14,639 --> 00:12:21,399 anyway automated testing it's 100% 313 00:12:18,560 --> 00:12:23,279 totally worth it uh it was worth it for 314 00:12:21,399 --> 00:12:25,560 us I'm pretty sure it's going to be 315 00:12:23,279 --> 00:12:27,360 worth it for you uh I really think this 316 00:12:25,560 --> 00:12:29,440 is important there are still a lot of 317 00:12:27,360 --> 00:12:31,880 packages that don't have 100% test 318 00:12:29,440 --> 00:12:33,680 coverage there are like really major 319 00:12:31,880 --> 00:12:37,800 python packages where you go to their 320 00:12:33,680 --> 00:12:39,920 GitHub and it's like 84% coverage tests 321 00:12:37,800 --> 00:12:42,279 failing and you know these things are 322 00:12:39,920 --> 00:12:45,320 like running the world and you just 323 00:12:42,279 --> 00:12:46,560 think really and if you're a new package 324 00:12:45,320 --> 00:12:48,279 and you're trying to like you know 325 00:12:46,560 --> 00:12:49,720 establish some credibility and trust 326 00:12:48,279 --> 00:12:51,800 those sort of those badges and those 327 00:12:49,720 --> 00:12:53,199 status indicators you know they matter 328 00:12:51,800 --> 00:12:54,680 they make a big difference to whether 329 00:12:53,199 --> 00:12:57,000 people take a look at what you've got 330 00:12:54,680 --> 00:12:59,920 and go yeah I'll happily use it or 331 00:12:57,000 --> 00:13:02,040 whether they go I might just wait so I 332 00:12:59,920 --> 00:13:04,279 think it's important for that trust in 333 00:13:02,040 --> 00:13:07,560 the package it's also really important 334 00:13:04,279 --> 00:13:09,519 for agility like if um if a dependency 335 00:13:07,560 --> 00:13:11,560 has a security issue because it's you 336 00:13:09,519 --> 00:13:13,839 know become outdated you know you can 337 00:13:11,560 --> 00:13:16,120 just like push push go on that merge 338 00:13:13,839 --> 00:13:17,920 request very confidently and you don't 339 00:13:16,120 --> 00:13:20,920 feel like things are going to break at 340 00:13:17,920 --> 00:13:22,760 all and it's also been very helpful in 341 00:13:20,920 --> 00:13:25,120 making sure we support good Library 342 00:13:22,760 --> 00:13:27,040 compatibility compliance like people 343 00:13:25,120 --> 00:13:28,880 might be aware one of the major 344 00:13:27,040 --> 00:13:33,079 mathematical libraries recently went 345 00:13:28,880 --> 00:13:34,399 from from like the I think it was the H 346 00:13:33,079 --> 00:13:36,079 the exact versions don't matter we'll 347 00:13:34,399 --> 00:13:38,760 call it 1.6 to 348 00:13:36,079 --> 00:13:40,800 2.1 and just like tons of stuff on the 349 00:13:38,760 --> 00:13:42,839 internet broke and it took like 3 months 350 00:13:40,800 --> 00:13:46,480 for all of the packages to go oh now we 351 00:13:42,839 --> 00:13:48,720 need to fix it and that was because 352 00:13:46,480 --> 00:13:51,519 people didn't have well partly because 353 00:13:48,720 --> 00:13:53,240 of the sver thing where people were just 354 00:13:51,519 --> 00:13:55,000 using the latest package regardless of 355 00:13:53,240 --> 00:13:56,800 major version numbers but it's also 356 00:13:55,000 --> 00:13:59,240 partly because the test cases weren't 357 00:13:56,800 --> 00:14:01,279 hitting it in all cases so being able to 358 00:13:59,240 --> 00:14:02,680 just kind of confidently move forward 359 00:14:01,279 --> 00:14:04,440 know that you're going to discover new 360 00:14:02,680 --> 00:14:06,399 issues during development rather than 361 00:14:04,440 --> 00:14:08,040 finding them on the release it's just 362 00:14:06,399 --> 00:14:11,199 incredibly helpful if you're a package 363 00:14:08,040 --> 00:14:11,199 manager to have this in 364 00:14:11,959 --> 00:14:16,440 place uh some experiences with automated 365 00:14:14,680 --> 00:14:18,480 testing troubleshooting and a couple 366 00:14:16,440 --> 00:14:20,600 from Beyond the scope of this you know 367 00:14:18,480 --> 00:14:22,199 our open source Journey so like a common 368 00:14:20,600 --> 00:14:24,680 one performance tests are too slow to 369 00:14:22,199 --> 00:14:27,320 automate people will often have like 370 00:14:24,680 --> 00:14:28,600 large realistic test data files they use 371 00:14:27,320 --> 00:14:31,240 to drive through their package to make 372 00:14:28,600 --> 00:14:33,560 sure everything okay that's fine that 373 00:14:31,240 --> 00:14:37,079 doesn't need to prevent you from doing 374 00:14:33,560 --> 00:14:38,680 good 100% coverage so that's that's a 375 00:14:37,079 --> 00:14:40,519 really important thing and we've taken a 376 00:14:38,680 --> 00:14:43,440 number of the scores contributors 377 00:14:40,519 --> 00:14:45,320 through like how to do that you know how 378 00:14:43,440 --> 00:14:47,199 how to go away from this kind of like 379 00:14:45,320 --> 00:14:49,759 large file on dis mentality to a 380 00:14:47,199 --> 00:14:52,279 separation of what the automated testing 381 00:14:49,759 --> 00:14:55,959 is covering and what else you also need 382 00:14:52,279 --> 00:14:57,639 to cover sort of separately um guey code 383 00:14:55,959 --> 00:14:59,079 is hard to test I just couldn't help 384 00:14:57,639 --> 00:15:01,519 throw that in there that's more from my 385 00:14:59,079 --> 00:15:03,560 past life um just don't put your 386 00:15:01,519 --> 00:15:05,440 application logic inside the click 387 00:15:03,560 --> 00:15:07,959 Handler make it separate make it 388 00:15:05,440 --> 00:15:09,800 callable make the click Handler call a 389 00:15:07,959 --> 00:15:12,079 callable function that's testable if at 390 00:15:09,800 --> 00:15:14,040 all possible make the the memory and 391 00:15:12,079 --> 00:15:17,360 state model of the application shouldn't 392 00:15:14,040 --> 00:15:19,920 be the state of the goey uh similar for 393 00:15:17,360 --> 00:15:23,000 command lines except life's generally a 394 00:15:19,920 --> 00:15:24,800 little easier uh applications processing 395 00:15:23,000 --> 00:15:26,440 a lot of files on dis is pretty common 396 00:15:24,800 --> 00:15:28,639 in the in the sort of science space 397 00:15:26,440 --> 00:15:31,440 where you've got like you know carefully 398 00:15:28,639 --> 00:15:33,360 craft Ed you know mathematical array 399 00:15:31,440 --> 00:15:36,839 based inputs that match precisely 400 00:15:33,360 --> 00:15:39,279 various outputs a lot of the sort of 401 00:15:36,839 --> 00:15:41,319 domain people so you know in my case 402 00:15:39,279 --> 00:15:43,279 scientists but in you know any case the 403 00:15:41,319 --> 00:15:45,800 domain people might be quite comfortable 404 00:15:43,279 --> 00:15:47,759 creating those test rigs as like files 405 00:15:45,800 --> 00:15:49,839 and file formats they know how to make 406 00:15:47,759 --> 00:15:53,800 maybe in applications they're familiar 407 00:15:49,839 --> 00:15:55,600 with um it gets a little and as a result 408 00:15:53,800 --> 00:15:57,360 a lot of the functional part of your 409 00:15:55,600 --> 00:15:59,199 application can end up just going to 410 00:15:57,360 --> 00:16:01,560 direct to disk and taking files names 411 00:15:59,199 --> 00:16:04,160 and passing file names around and then 412 00:16:01,560 --> 00:16:06,199 when it comes time to test it like it's 413 00:16:04,160 --> 00:16:09,399 really hard it's either slow because 414 00:16:06,199 --> 00:16:11,519 even with SSD disc is slower than memory 415 00:16:09,399 --> 00:16:13,519 or it's really flaky CU you've got to 416 00:16:11,519 --> 00:16:15,560 like pass around strings and manage 417 00:16:13,519 --> 00:16:17,519 program State you know manage the state 418 00:16:15,560 --> 00:16:19,319 of the variables in your automated tests 419 00:16:17,519 --> 00:16:21,399 and you can't just get in there and 420 00:16:19,319 --> 00:16:24,560 interpose terribly easily it starts 421 00:16:21,399 --> 00:16:26,440 getting a little bit bit narly moving to 422 00:16:24,560 --> 00:16:28,399 something which passes around fil like 423 00:16:26,440 --> 00:16:30,880 objects allows you to create data on the 424 00:16:28,399 --> 00:16:32,959 Fly into straight into memory without 425 00:16:30,880 --> 00:16:34,639 hitting the disc it's much quicker uh 426 00:16:32,959 --> 00:16:36,199 and it allows you to have a more modular 427 00:16:34,639 --> 00:16:37,360 design that's going to let you interpose 428 00:16:36,199 --> 00:16:40,000 on 429 00:16:37,360 --> 00:16:42,120 things so this is one of the thing like 430 00:16:40,000 --> 00:16:44,319 like a point like that is why I'm not 431 00:16:42,120 --> 00:16:45,880 ready like this is this is like my story 432 00:16:44,319 --> 00:16:48,360 I don't know if I can give that advice 433 00:16:45,880 --> 00:16:50,160 to to kind of everyone you know what's 434 00:16:48,360 --> 00:16:51,600 exciting about that well it mattered to 435 00:16:50,160 --> 00:16:54,720 me and it mattered to creating this 436 00:16:51,600 --> 00:16:57,199 package rather than so it's an example 437 00:16:54,720 --> 00:16:58,920 some random tips on testing uh hard to 438 00:16:57,199 --> 00:17:01,600 cover all of them but work out how many 439 00:16:58,920 --> 00:17:04,240 decimal places to test to and do it 440 00:17:01,600 --> 00:17:06,520 consistently um computers are both 441 00:17:04,240 --> 00:17:10,079 brilliant at maths and like kind of bad 442 00:17:06,520 --> 00:17:12,199 at maths um if you do the wrong sort of 443 00:17:10,079 --> 00:17:13,799 order of operations or something changes 444 00:17:12,199 --> 00:17:15,640 you are going to get different numbers 445 00:17:13,799 --> 00:17:18,120 down in the fine scale of those decimal 446 00:17:15,640 --> 00:17:21,319 places and you will need to figure out 447 00:17:18,120 --> 00:17:24,039 if that matters to you um so yeah we 448 00:17:21,319 --> 00:17:25,559 figured out a number of decimal places 449 00:17:24,039 --> 00:17:28,960 and more or less standardized on it it's 450 00:17:25,559 --> 00:17:31,039 a good idea um with the test data I was 451 00:17:28,960 --> 00:17:33,640 referring to previously essentially we 452 00:17:31,039 --> 00:17:35,600 stored it inside piy files that makes it 453 00:17:33,640 --> 00:17:37,679 pretty easily discoverable by the test 454 00:17:35,600 --> 00:17:40,720 Rigs and the test fixtures means you can 455 00:17:37,679 --> 00:17:43,240 import your test data e easily and you 456 00:17:40,720 --> 00:17:44,720 don't have to sort of you know do a 457 00:17:43,240 --> 00:17:46,760 little bit of used to be called like 458 00:17:44,720 --> 00:17:48,440 reflection apis to like discover what 459 00:17:46,760 --> 00:17:49,840 directory you happen to be sitting in at 460 00:17:48,440 --> 00:17:51,280 the moment and where your source code 461 00:17:49,840 --> 00:17:53,240 happens to be coming from and where you 462 00:17:51,280 --> 00:17:55,360 think your test files probably are in 463 00:17:53,240 --> 00:17:57,720 order to load them into memory if you 464 00:17:55,360 --> 00:17:59,559 can just put it straight in a pi file 465 00:17:57,720 --> 00:18:03,559 it's a bit bit more straight 466 00:17:59,559 --> 00:18:07,360 forward um and if your code is test hard 467 00:18:03,559 --> 00:18:12,720 to test can indicate a problem with the 468 00:18:07,360 --> 00:18:15,559 code okay typ hinting was a journey uh 469 00:18:12,720 --> 00:18:16,840 I'm not bitter at all um so this is a 470 00:18:15,559 --> 00:18:19,000 situation where I've got a pretty 471 00:18:16,840 --> 00:18:21,159 different opinion to the norm so I want 472 00:18:19,000 --> 00:18:23,559 to both give you my opinion but also 473 00:18:21,159 --> 00:18:25,679 explain to you that it is not the 474 00:18:23,559 --> 00:18:27,760 commonly held wisdom so that you know 475 00:18:25,679 --> 00:18:30,280 like both of those things are clear okay 476 00:18:27,760 --> 00:18:32,280 so a lot of people really like typ pins 477 00:18:30,280 --> 00:18:34,280 like and if you're like well I'm 478 00:18:32,280 --> 00:18:35,440 handling forms all day long and I really 479 00:18:34,280 --> 00:18:37,360 really need to know the difference 480 00:18:35,440 --> 00:18:39,159 between an integer and a string like 481 00:18:37,360 --> 00:18:42,280 that's fair that's crucial to your 482 00:18:39,159 --> 00:18:44,840 application logic uh I wanted to write 483 00:18:42,280 --> 00:18:47,360 really General code and a lot of the 484 00:18:44,840 --> 00:18:50,919 functions like I could support like an 485 00:18:47,360 --> 00:18:54,480 INT or a list of ins or a python array 486 00:18:50,919 --> 00:18:58,559 of ins or a numpy of ins or any kind of 487 00:18:54,480 --> 00:19:00,520 number really or xarray object or pandas 488 00:18:58,559 --> 00:19:02,679 or any one of about three or four 489 00:19:00,520 --> 00:19:05,559 different pandas Alternatives and the 490 00:19:02,679 --> 00:19:07,280 major xarray alternative and it would be 491 00:19:05,559 --> 00:19:10,039 kind of nice to support like the back 492 00:19:07,280 --> 00:19:12,480 ends for like pie torch and tensor flow 493 00:19:10,039 --> 00:19:15,360 at the same time and that's like that's 494 00:19:12,480 --> 00:19:18,919 all reasonable for maths so trying to 495 00:19:15,360 --> 00:19:21,919 typ hint that is actually kind of pretty 496 00:19:18,919 --> 00:19:24,440 complicated and like one of those 497 00:19:21,919 --> 00:19:26,679 libraries and I'm not going to name them 498 00:19:24,440 --> 00:19:29,159 you cannot inherit from like that they 499 00:19:26,679 --> 00:19:30,960 have done funky funky metaprogramming 500 00:19:29,159 --> 00:19:32,520 and you just like you can't do it and if 501 00:19:30,960 --> 00:19:34,919 you want to have an extension to their 502 00:19:32,520 --> 00:19:37,320 classes you have to use their funky 503 00:19:34,919 --> 00:19:40,480 registration process to add your add 504 00:19:37,320 --> 00:19:43,919 your functionality into their classes so 505 00:19:40,480 --> 00:19:46,400 TI penting was very difficult and not 506 00:19:43,919 --> 00:19:47,520 very helpful for these complex compound 507 00:19:46,400 --> 00:19:49,320 types where you're trying to write 508 00:19:47,520 --> 00:19:51,120 polymorphic code that can just handle 509 00:19:49,320 --> 00:19:53,080 whatever you throw at it which I was 510 00:19:51,120 --> 00:19:56,080 happy to do you know we were happy to do 511 00:19:53,080 --> 00:19:58,200 we could easily handle it but on the 512 00:19:56,080 --> 00:19:59,960 other hand people wanted that sense of 513 00:19:58,200 --> 00:20:02,280 safety comes from type hinting and I've 514 00:19:59,960 --> 00:20:04,559 also seen this gradual move from type 515 00:20:02,280 --> 00:20:07,400 hints which sounds kind of you know free 516 00:20:04,559 --> 00:20:09,080 flowing and relaxed to type annotations 517 00:20:07,400 --> 00:20:12,280 which sounds a little bit more formal 518 00:20:09,080 --> 00:20:15,240 and a little bit more expected so I 519 00:20:12,280 --> 00:20:17,480 think you know the world will thank you 520 00:20:15,240 --> 00:20:19,679 for providing type hinting and type anot 521 00:20:17,480 --> 00:20:21,520 annotations that will thank you for 522 00:20:19,679 --> 00:20:22,919 providing that information on your apis 523 00:20:21,520 --> 00:20:24,720 which I think is fairly appropriate in 524 00:20:22,919 --> 00:20:27,720 terms of like return types and things 525 00:20:24,720 --> 00:20:29,400 like that but at the same time it's not 526 00:20:27,720 --> 00:20:31,320 necessarily inform and it can be 527 00:20:29,400 --> 00:20:32,880 actively misleading when the code itself 528 00:20:31,320 --> 00:20:36,240 will comfortably support multiple 529 00:20:32,880 --> 00:20:39,360 different types um which passed um but 530 00:20:36,240 --> 00:20:39,360 it's easiest to just 531 00:20:39,400 --> 00:20:44,840 conform linting and static analysis this 532 00:20:43,480 --> 00:20:46,919 there's there's a lot that's been said 533 00:20:44,840 --> 00:20:48,880 on lenting and static analysis uh this 534 00:20:46,919 --> 00:20:51,799 is kind of my take like black is useful 535 00:20:48,880 --> 00:20:54,640 and fast just use it isort is useful and 536 00:20:51,799 --> 00:20:56,440 fast just use it rough is a recently 537 00:20:54,640 --> 00:20:59,000 developed tool which is kind of really 538 00:20:56,440 --> 00:21:01,960 interesting so it's very fast and a lot 539 00:20:59,000 --> 00:21:03,760 of the time like Fast tools are very 540 00:21:01,960 --> 00:21:06,000 comfortable to adopt because they fit 541 00:21:03,760 --> 00:21:09,240 very neatly direct into the editor 542 00:21:06,000 --> 00:21:11,679 experience um but it doesn't have enough 543 00:21:09,240 --> 00:21:14,240 uh kind of functional coverage for me at 544 00:21:11,679 --> 00:21:15,799 the moment compared to like you know 545 00:21:14,240 --> 00:21:17,400 pilent or or something that's going to 546 00:21:15,799 --> 00:21:20,480 check a few more 547 00:21:17,400 --> 00:21:22,559 things um and yeah security static 548 00:21:20,480 --> 00:21:25,760 analysis you'll have to do some reading 549 00:21:22,559 --> 00:21:27,400 on on the Security Management as 550 00:21:25,760 --> 00:21:30,080 well 551 00:21:27,400 --> 00:21:32,480 documentation uh we we lent into 552 00:21:30,080 --> 00:21:35,679 documentation and we we lent in hard and 553 00:21:32,480 --> 00:21:38,240 it was just well worth it so here are 554 00:21:35,679 --> 00:21:40,840 the kinds of documentation that you 555 00:21:38,240 --> 00:21:43,240 might want to consider writing uh we did 556 00:21:40,840 --> 00:21:46,640 all of these uh and all of them have 557 00:21:43,240 --> 00:21:48,400 helped in their various ways so dock 558 00:21:46,640 --> 00:21:50,960 strings and code comments the major 559 00:21:48,400 --> 00:21:52,400 dispute that I hear on dock strings and 560 00:21:50,960 --> 00:21:54,440 code comments among people from 561 00:21:52,400 --> 00:21:56,400 different perspectives is that well the 562 00:21:54,440 --> 00:21:58,039 code does what the code does it doesn't 563 00:21:56,400 --> 00:22:01,600 write doesn't do what the comments or 564 00:21:58,039 --> 00:22:03,840 the docs string say um I would generally 565 00:22:01,600 --> 00:22:05,919 argue that even even an incorrect dock 566 00:22:03,840 --> 00:22:08,600 string or comment can be remarkably 567 00:22:05,919 --> 00:22:10,559 illustrative to the intent or hopes of 568 00:22:08,600 --> 00:22:12,360 the person that wrote the code and that 569 00:22:10,559 --> 00:22:13,919 there is not really a source of truth 570 00:22:12,360 --> 00:22:16,000 about what should be happening in the 571 00:22:13,919 --> 00:22:18,159 code regardless of what is happening in 572 00:22:16,000 --> 00:22:19,760 the code uh and certainly people 573 00:22:18,159 --> 00:22:21,760 appreciate having a lot of good 574 00:22:19,760 --> 00:22:22,760 information uh particularly around the 575 00:22:21,760 --> 00:22:25,960 API 576 00:22:22,760 --> 00:22:27,880 docs contributor guides have been mainly 577 00:22:25,960 --> 00:22:29,799 helpful for me as the package maintainer 578 00:22:27,880 --> 00:22:31,600 like in theory there for everyone else 579 00:22:29,799 --> 00:22:33,360 but actually like to a large degree 580 00:22:31,600 --> 00:22:35,640 they're a reminder to me of what I asked 581 00:22:33,360 --> 00:22:37,799 people to do so that I can be reasonably 582 00:22:35,640 --> 00:22:40,120 consistent uh because left to my own 583 00:22:37,799 --> 00:22:42,880 devices I'll be wildly inconsistent and 584 00:22:40,120 --> 00:22:44,760 confuse everybody so it's it's been a 585 00:22:42,880 --> 00:22:46,640 helpful Aid to memory for me to be able 586 00:22:44,760 --> 00:22:48,159 to work through things and it means that 587 00:22:46,640 --> 00:22:50,520 if someone else needs to you know 588 00:22:48,159 --> 00:22:53,120 oversee a merge request process or pull 589 00:22:50,520 --> 00:22:55,400 request process for a period it's fine 590 00:22:53,120 --> 00:22:57,240 uh websites like you know like 591 00:22:55,400 --> 00:22:58,919 technically you don't need one you know 592 00:22:57,240 --> 00:23:01,120 you can just put your code out there on 593 00:22:58,919 --> 00:23:02,440 on GitHub you don't need to go to Pipi 594 00:23:01,120 --> 00:23:05,320 either you can just make your code 595 00:23:02,440 --> 00:23:08,240 available it won't be like you won't get 596 00:23:05,320 --> 00:23:10,760 in trouble for not doing it but it's 597 00:23:08,240 --> 00:23:13,080 obviously essential to 598 00:23:10,760 --> 00:23:15,400 discoverability uh consider examples 599 00:23:13,080 --> 00:23:17,480 tutorials and notebooks I think there's 600 00:23:15,400 --> 00:23:19,919 a rant later in this talk about making 601 00:23:17,480 --> 00:23:21,600 your tutorials work but just in case I 602 00:23:19,919 --> 00:23:24,640 forgot to include that slide I'm going 603 00:23:21,600 --> 00:23:26,480 to do it twice it's really important at 604 00:23:24,640 --> 00:23:29,640 least to me to make the tutorials 605 00:23:26,480 --> 00:23:32,240 actually work um I lost I would I would 606 00:23:29,640 --> 00:23:35,440 estimate like straight up weeks like you 607 00:23:32,240 --> 00:23:38,039 know 8 hours per per day times 5 days a 608 00:23:35,440 --> 00:23:39,840 week times some number of weeks on 609 00:23:38,039 --> 00:23:41,919 tutorials that just didn't work just 610 00:23:39,840 --> 00:23:44,880 like debugging someone's tutorial out 611 00:23:41,919 --> 00:23:47,200 there that is simply like nonfunctional 612 00:23:44,880 --> 00:23:50,120 and maybe my success rate at like making 613 00:23:47,200 --> 00:23:52,679 the tutorial function is maybe like 25% 614 00:23:50,120 --> 00:23:54,480 like 75% of the time it's like well the 615 00:23:52,679 --> 00:23:56,200 source data is moved and is gone and 616 00:23:54,480 --> 00:23:57,799 requires a sign up and all the versions 617 00:23:56,200 --> 00:24:00,000 of all of the things in this in this 618 00:23:57,799 --> 00:24:03,799 tutorial of changed and I just you know 619 00:24:00,000 --> 00:24:08,440 like didn't get there so yeah again not 620 00:24:03,799 --> 00:24:09,440 bitter at all but our tutorials work so 621 00:24:08,440 --> 00:24:12,480 you know 622 00:24:09,440 --> 00:24:14,279 like perfect perfect testing like could 623 00:24:12,480 --> 00:24:16,720 they ever break for a short period of 624 00:24:14,279 --> 00:24:18,559 time until we fix it yes it's possible 625 00:24:16,720 --> 00:24:20,840 but we actively maintain them so you 626 00:24:18,559 --> 00:24:22,840 know like feel free to go find a broken 627 00:24:20,840 --> 00:24:25,880 tutorial and prove me wrong but we will 628 00:24:22,840 --> 00:24:25,880 fix it right back at 629 00:24:26,159 --> 00:24:31,320 you okay so how to do strings give every 630 00:24:29,320 --> 00:24:33,200 function a dock string the exceptions to 631 00:24:31,320 --> 00:24:34,600 this rule aren't worth arguing over 632 00:24:33,200 --> 00:24:38,679 certainly not in a 633 00:24:34,600 --> 00:24:41,279 presentation uh comment liberally uh 634 00:24:38,679 --> 00:24:43,520 relating a few nebulously connected 635 00:24:41,279 --> 00:24:46,559 comments like dock strings math Jacks 636 00:24:43,520 --> 00:24:48,840 web pages tutorials and Doc strings like 637 00:24:46,559 --> 00:24:52,080 they have helped me find bugs doing code 638 00:24:48,840 --> 00:24:55,960 reviews in other people's code often so 639 00:24:52,080 --> 00:24:58,000 it it is very important because 640 00:24:55,960 --> 00:25:01,200 programmers all of us we're all just you 641 00:24:58,000 --> 00:25:04,000 know flawed humans and our expression in 642 00:25:01,200 --> 00:25:05,919 code is not necessarily perfect and so 643 00:25:04,000 --> 00:25:09,240 expressing our ideas twice in two 644 00:25:05,919 --> 00:25:11,720 different forms fixes bugs uh which is I 645 00:25:09,240 --> 00:25:13,520 think you know important I don't think 646 00:25:11,720 --> 00:25:15,000 that's like the most important like the 647 00:25:13,520 --> 00:25:17,520 most important thing is that other 648 00:25:15,000 --> 00:25:19,760 developers can go back later and read it 649 00:25:17,520 --> 00:25:21,919 or like you in 3 months or if you have a 650 00:25:19,760 --> 00:25:23,679 short memory like me like a couple of 651 00:25:21,919 --> 00:25:24,960 days later it tells you what you were 652 00:25:23,679 --> 00:25:28,320 trying to do in the first place that's 653 00:25:24,960 --> 00:25:30,039 very important um we've used Napoleon 654 00:25:28,320 --> 00:25:31,600 style do strings I have no idea why 655 00:25:30,039 --> 00:25:33,440 they're called Napoleon style dock 656 00:25:31,600 --> 00:25:35,600 strings I assume Napoleon didn't invent 657 00:25:33,440 --> 00:25:38,120 them but I haven't gone further um but 658 00:25:35,600 --> 00:25:40,480 it has been a reasonable Choice uh and 659 00:25:38,120 --> 00:25:42,799 we use it to drive the API docs 660 00:25:40,480 --> 00:25:47,200 obviously so the documentation text 661 00:25:42,799 --> 00:25:50,000 stack uh I only found this one like this 662 00:25:47,200 --> 00:25:52,559 YouTube video like this just fixed it 663 00:25:50,000 --> 00:25:55,440 for me this was this was the answer um 664 00:25:52,559 --> 00:25:57,200 so thank you to whomever uh and 665 00:25:55,440 --> 00:25:59,760 apologies I don't know the pronunciation 666 00:25:57,200 --> 00:26:03,760 of the native language here Yan Louie 667 00:25:59,760 --> 00:26:05,200 Koo Rodriguez thank you um this was what 668 00:26:03,760 --> 00:26:07,360 allowed us to string together the 669 00:26:05,200 --> 00:26:09,320 technologies that we wanted to work with 670 00:26:07,360 --> 00:26:11,000 Sphinx Can Go the Distance on the 671 00:26:09,320 --> 00:26:14,120 functionality you want in constructing 672 00:26:11,000 --> 00:26:17,440 the web page um markdown at least among 673 00:26:14,120 --> 00:26:20,279 this particular development team was 674 00:26:17,440 --> 00:26:22,919 universally uh more pleasing to write 675 00:26:20,279 --> 00:26:24,720 documentation in and this particular 676 00:26:22,919 --> 00:26:28,360 Tech stack allows us to stitch all the 677 00:26:24,720 --> 00:26:30,399 tools together it was a great choice 678 00:26:28,360 --> 00:26:31,799 right the source code for documentation 679 00:26:30,399 --> 00:26:33,320 okay this is kind of like the problem 680 00:26:31,799 --> 00:26:35,760 you don't want to have but it's going to 681 00:26:33,320 --> 00:26:37,399 be there uh the documentation is like 682 00:26:35,760 --> 00:26:40,760 this little world of its own and it 683 00:26:37,399 --> 00:26:44,440 looks so innocent how markdown files can 684 00:26:40,760 --> 00:26:48,039 have so much complexity is remarkable 685 00:26:44,440 --> 00:26:50,000 they will render differently everywhere 686 00:26:48,039 --> 00:26:51,640 and it's a challenge and it's a thing 687 00:26:50,000 --> 00:26:54,159 and there are rules that I've tried to 688 00:26:51,640 --> 00:26:56,000 document that I can't even express in 689 00:26:54,159 --> 00:26:58,559 English I just like remember that 690 00:26:56,000 --> 00:27:00,880 magically that part of the of that style 691 00:26:58,559 --> 00:27:03,760 of markdown in that kind of API string 692 00:27:00,880 --> 00:27:06,279 in that kind of way I have to do this 693 00:27:03,760 --> 00:27:07,600 slightly differently there and I've just 694 00:27:06,279 --> 00:27:09,559 never been able to explain all the 695 00:27:07,600 --> 00:27:11,320 details so we've tried to achieve 696 00:27:09,559 --> 00:27:15,279 consistency between and I'll just go 697 00:27:11,320 --> 00:27:17,720 through the list pii GitHub front page 698 00:27:15,279 --> 00:27:20,679 GitHub viewing the documentation folder 699 00:27:17,720 --> 00:27:24,360 GitHub looking at the tutorial folder uh 700 00:27:20,679 --> 00:27:26,760 cuz the read me goes onto pii uh local 701 00:27:24,360 --> 00:27:28,640 builds of the documentation people 702 00:27:26,760 --> 00:27:30,360 actually running actual Jupiter lab for 703 00:27:28,640 --> 00:27:32,440 our tutorials as opposed to the 704 00:27:30,360 --> 00:27:35,640 documentation rendered version of the 705 00:27:32,440 --> 00:27:38,039 tutorials read the docs versions of all 706 00:27:35,640 --> 00:27:41,240 of the things that I just mentioned and 707 00:27:38,039 --> 00:27:44,799 binder and NB viewer so that's like 10 708 00:27:41,240 --> 00:27:47,320 different like rendering contexts plus 709 00:27:44,799 --> 00:27:48,960 actually reading the markdown files uh 710 00:27:47,320 --> 00:27:51,440 we had to make some compromises some 711 00:27:48,960 --> 00:27:54,000 things were just not possible to support 712 00:27:51,440 --> 00:27:57,039 the greatest thing we ever did was make 713 00:27:54,000 --> 00:27:59,159 this 228 Branch where we can just push 714 00:27:57,039 --> 00:28:01,840 stuff and every one remembers what the 715 00:27:59,159 --> 00:28:03,679 URL is and if someone says hey my pull 716 00:28:01,840 --> 00:28:06,279 request is good to go can you show it to 717 00:28:03,679 --> 00:28:08,039 me we just force push it to 228 it 718 00:28:06,279 --> 00:28:10,320 renders and read the docs on a in a 719 00:28:08,039 --> 00:28:11,880 hidden link and we go check it out and 720 00:28:10,320 --> 00:28:13,960 that's been incredibly helpful because 721 00:28:11,880 --> 00:28:15,720 not everyone's it's not actually hard to 722 00:28:13,960 --> 00:28:17,880 build the documentation like that that 723 00:28:15,720 --> 00:28:19,000 bit is really quite straightforward um 724 00:28:17,880 --> 00:28:20,360 but a lot of people feel more 725 00:28:19,000 --> 00:28:22,039 comfortable when they see it for real 726 00:28:20,360 --> 00:28:25,559 zase on the 727 00:28:22,039 --> 00:28:28,279 internet the good news is that everybody 728 00:28:25,559 --> 00:28:31,679 really really appreciates good document 729 00:28:28,279 --> 00:28:34,159 a um if if your part of your motivation 730 00:28:31,679 --> 00:28:35,559 is to get adopted like do good 731 00:28:34,159 --> 00:28:36,799 documentation it's going to make 732 00:28:35,559 --> 00:28:39,399 probably a bigger difference than 733 00:28:36,799 --> 00:28:41,600 anything else people will happily have 734 00:28:39,399 --> 00:28:43,960 half as much functionality and twice as 735 00:28:41,600 --> 00:28:47,360 much documentation and something 736 00:28:43,960 --> 00:28:49,440 reliable um I feel like narratively I've 737 00:28:47,360 --> 00:28:50,640 covered a lot of this already um but I 738 00:28:49,440 --> 00:28:52,640 think it's very much helped with 739 00:28:50,640 --> 00:28:54,360 onboarding people and if you have a 740 00:28:52,640 --> 00:28:56,440 particular domain or field that you're 741 00:28:54,360 --> 00:28:58,600 working in it can also help people from 742 00:28:56,440 --> 00:29:00,720 the domain perspective on board into 743 00:28:58,600 --> 00:29:03,519 into their side of the process as well 744 00:29:00,720 --> 00:29:07,159 and I really like looking at math 745 00:29:03,519 --> 00:29:08,919 Jacks okay ecosystem the rules are not 746 00:29:07,159 --> 00:29:10,799 obvious and this was the this was the 747 00:29:08,919 --> 00:29:13,360 biggest thing where like no amount of 748 00:29:10,799 --> 00:29:15,440 like internet search could answer these 749 00:29:13,360 --> 00:29:17,799 questions for me it it just experience 750 00:29:15,440 --> 00:29:19,600 only taught me these things possibly I'm 751 00:29:17,799 --> 00:29:21,799 wrong possibly I'm not I was naive at 752 00:29:19,600 --> 00:29:24,760 the outset um but these were the things 753 00:29:21,799 --> 00:29:27,399 I discovered so sver you basically have 754 00:29:24,760 --> 00:29:28,960 to do it release notes that's totally 755 00:29:27,399 --> 00:29:31,320 free form you can do anything you want 756 00:29:28,960 --> 00:29:34,440 with your release notes within reason uh 757 00:29:31,320 --> 00:29:36,240 the process like how to publish to Pipi 758 00:29:34,440 --> 00:29:38,159 like discovering the one recommended 759 00:29:36,240 --> 00:29:39,880 path was very difficult because there 760 00:29:38,159 --> 00:29:42,640 are very very many paths that are 761 00:29:39,880 --> 00:29:44,519 referred to online and a lot of those 762 00:29:42,640 --> 00:29:47,080 guides are outdated and I had a really 763 00:29:44,519 --> 00:29:48,960 hard time figuring out our process is 764 00:29:47,080 --> 00:29:50,679 straightforward I have one minute to go 765 00:29:48,960 --> 00:29:51,760 we tag the releases use compatible 766 00:29:50,679 --> 00:29:54,240 versions they're much better than 767 00:29:51,760 --> 00:29:56,080 greater than or equal to how and what to 768 00:29:54,240 --> 00:29:58,120 automate we don't didn't automate 769 00:29:56,080 --> 00:30:00,320 anything we retained manual control of 770 00:29:58,120 --> 00:30:02,159 the final version publishing to places 771 00:30:00,320 --> 00:30:05,760 that was a good call basically 772 00:30:02,159 --> 00:30:08,039 everything else is automated lean into 773 00:30:05,760 --> 00:30:09,840 automation Community considerations and 774 00:30:08,039 --> 00:30:12,720 I've just been given the one minute flag 775 00:30:09,840 --> 00:30:15,240 so uh this should be like there are and 776 00:30:12,720 --> 00:30:18,640 should be many talks on community 777 00:30:15,240 --> 00:30:20,279 considerations um the main thing that we 778 00:30:18,640 --> 00:30:22,200 kind of did upfront was make sure to 779 00:30:20,279 --> 00:30:24,320 have a good code of conduct and and make 780 00:30:22,200 --> 00:30:27,000 sure the contributor and the contributor 781 00:30:24,320 --> 00:30:29,080 Covenant is now widely adopted and and 782 00:30:27,000 --> 00:30:31,840 well respected so in the past it was 783 00:30:29,080 --> 00:30:33,440 much more much less clear how to how to 784 00:30:31,840 --> 00:30:36,159 do this in a way that's going to work 785 00:30:33,440 --> 00:30:39,519 for everyone now it's pretty 786 00:30:36,159 --> 00:30:41,519 good okay we published a paper in the 787 00:30:39,519 --> 00:30:43,840 Journal of Open Source software in some 788 00:30:41,519 --> 00:30:45,159 disciplines uh academic citations are 789 00:30:43,840 --> 00:30:46,720 really how people are going to be able 790 00:30:45,159 --> 00:30:49,679 to get recognition for their work and 791 00:30:46,720 --> 00:30:52,120 it's very important so if you do publish 792 00:30:49,679 --> 00:30:53,799 your own package consider an academic 793 00:30:52,120 --> 00:30:55,960 publication such as in the Journal of 794 00:30:53,799 --> 00:30:57,600 Open Source software uh it's a great way 795 00:30:55,960 --> 00:30:59,440 to support your colleagues if you're 796 00:30:57,600 --> 00:31:02,120 working in an environment where you want 797 00:30:59,440 --> 00:31:05,559 to get the scientists on board with your 798 00:31:02,120 --> 00:31:07,200 work and we are one slide away uh but 799 00:31:05,559 --> 00:31:09,639 I'd like to thank all of the 800 00:31:07,200 --> 00:31:11,480 contributors to our open source packages 801 00:31:09,639 --> 00:31:12,559 for a moment just to appreciate all of 802 00:31:11,480 --> 00:31:15,240 their 803 00:31:12,559 --> 00:31:17,760 work in conclusion it was a worthwhile 804 00:31:15,240 --> 00:31:19,240 experience and I hope perhaps that this 805 00:31:17,760 --> 00:31:21,000 may have help may be able to help 806 00:31:19,240 --> 00:31:26,240 someone else avoid some of the pain that 807 00:31:21,000 --> 00:31:26,240 we experienced along the way thank you 808 00:31:30,960 --> 00:31:34,240 thank you very much Tennessee for that 809 00:31:32,279 --> 00:31:38,480 awesome talk we've got a small gift of 810 00:31:34,240 --> 00:31:40,000 our appreciation this great Pon mug um 811 00:31:38,480 --> 00:31:41,720 we're not going to have any time for 812 00:31:40,000 --> 00:31:43,519 questions right now but I'm sure 813 00:31:41,720 --> 00:31:45,679 Tennessee is having a chat uh throughout 814 00:31:43,519 --> 00:31:47,600 the rest of the conference um we're 815 00:31:45,679 --> 00:31:49,200 going to have a small pause uh just for 816 00:31:47,600 --> 00:31:50,919 people to move around but the next talk 817 00:31:49,200 --> 00:31:53,639 in this room is going to be Simon Aubrey 818 00:31:50,919 --> 00:31:58,320 talking to us about duck DB so thank you 819 00:31:53,639 --> 00:31:58,320 let's W let's thank Tennessee once more