 Well, it's that time of the week again. It's time for chitchat across the pond. This is episode number 755 for December 10th, 2020 2022 and I'm your host Allison Sheridan. This week our guest is Bart Bouchotte's back with programming by stealth number 142. What's up today, Bart? Oh It's been quite a while here. I've been having so much fun trying not to kill myself in the frost, but so far so good I'm still here. I Almost had to put on a long-sleeve shirt. So yeah, I'm suffering too. Oh Oh, woogums. We were I was delighted today that it crossed zero So that meant that the ice got to go away. I literally saw people in down jackets You know tux, you know winter winter hats and Uggs and I was walking the dog in shorts and a t-shirt. I Was chilly. I'm not gonna lie, but really Uggs Yeah, I got made fun of because I was wearing shorts to work this week But I had like really good leg warmers underneath the shorts. So, but yeah, would you still have shorts on? I was like, yeah, but my legs are really warm Well, we aren't this week in weather we're gonna have to kick in it looks like we're gonna it's an exciting week I think it is so we are kicking off the official project to migrate The pearl XK pass WD module which I'm not gonna say its name because it's too difficult to say to a JavaScript module Which I'm going to call XK pass WD JS. I Can say that Yeah, I thought you might like that and Initially, I called it HS for haystacks because initially my thinking was to combine Steve Gibson's idea of basically repeating the same character over and over again to give you length for free with the concept of XK CD style wordy passwords and In reality, the only presets ever ended up using were ones that didn't repeat things because most Sorry, a lot of really naive password managers like oh, you're repeating something your password must be insecure and they stop you Okay, so the repetition thing doesn't work. So actually why bother pretending the haystacks are there now This is purely inspired by XK pass WD I guess the long the long part could have come from haystacks, but it was just too hard to say HS XK Those those four letters just don't work together. So You know, this makes me really happy. So it's XK pass WD JS. Yeah. Yeah, that's what I've decided on. So yeah I feel like we should have balloons. It's launching the project is launching Yay, so I guess the biggest part of the project launching means that the gate repository exists That's probably the biggest thing and I've also put quite a bit of work into an initial read me which has helped me sort of structure How I want to put the project together So you can bookmark this. This is the genuine repository And then the project is going to evolve in three phases So phase one is what I'm going to build at a project skeleton And to be honest simply creating the repository and this initial read me is part of that building out the skeleton So while we're in the skeleton phase, it's going to be basically me Arranging all the furniture and preparing for the party effectively and preparing to host guests So the big outcomes that need to be done before I'm before I consider the skeleton phase finished Is that the UML class diagram has to be completed because that is going to be our Bible for phase two, which I'll describe in a sec I also need to have ready to go when I open the doors contribution guides for the developers because if you want The last thing you want to do is to start building up technical debt From the start. I mean it is going to happen, but let's have that happen as far in the future as possible So don't don't bring it into the house first Really exactly don't walk in with your dirty shoes into a clean house It's at least try to keep it clean for a while So I want to have the various guides ready for developers outlining the code style I'll get branching policies our style guides for git commit Basically figure out exactly how we'd like to run the project and try to try to have it all documented in the in a friendly obvious Easy to follow way So because I want people to do things Right, but not because I'm an evil, you know school marm But because it's just I've made it easy and I've just asked people to please be nice and it should just work So that's sort of I want to make it as easy as possible For just to flow naturally that we do things right I'm gonna give you an analogy that that really says why this is such a great idea in the olden days in the Before Christ was born. I used to draw do drafting with a pencil or sometimes a pen on my lawyer and You know on a big old drafting board and one of the we eventually migrated over to using the computer And that was very exciting that we had 2d CAD at the time But an effort was begun to create standard notes So there were notes on die on on your parts that would say like bond per hb 8-5 That's the one I always remember was was that's what you always bonded two parts together with that was the bonding material It was the spec for it and what they wanted was it to always be written exactly that way They wanted standard notes and a lot of people, you know kind of got annoyed like I've always written it this way Because I'm a hundred years old and I don't ever want to change my ways and I looked at it It's like I really could care less about that. That's the last thing I just want to be able to go bond and it goes okay Which one this one click and it spits out the note for me So having a structure I think just freeze you up to do other stuff where you don't have to wonder Oh, does Bart like you know does Bart like spaces or tabs, you know, what am I gonna need to do here? And by the way, you can teach your if you're using visual studio code at least you can tell it when you save it Converts it to the way the style guide says so I can put two two spaces in and it'll make it tabs If that's what you want or vice versa. I think yeah, that's an helmet tells me anyway Oh, no, well, we're gonna be using JS lint So it's gonna be a JS lint config file in the project So your editor if it's JS lint aware will pick that up automatically and it means that if you're using it Any of the the modern editors it should just work Right, but it fixes it for you. You don't have to sit there You know getting yelled at all the time and fixing these little errors Exactly exactly. Yeah Like VS code will certainly just say oh, okay That's what they want in this project and you'll type away doing what you want and VS code will have your back And it will do whatever the spec says Yeah, so right and in theory in the big picture. We don't care. We want it all just to be consistent and No, you say we in some of these sentences and I suspect that it's mostly I as in Bart Will be making these rules, but perhaps with a an appeals process You have 51% of the vote, right? I guess I'll do a Mark Zuckerberg on it and say that I have the magic extra share You you know my old boss Bart always said it's a democracy, but I have 51% of the vote Okay, we'll go with that then But no, I'm completely open to you know Any sensible argument will always find a near with me But if your argument is because I have an emotional reason I want to do it this way you Less likely to succeed Right, right, but if it's practical and it solves some problems and that's that's a conversation at least to be had But I think again, that's just as important as this whole standard notes kind of thing I was talking about was you have to have somebody who has 51% of the vote. Otherwise it nothing gets done. I Believe the the common phrase is benevolent dictator in the software world the Linus Torvalds in the Linux kernel There's one guy who led PA was a Python for ages a Dutch guy who then retired and caused chaos it's A lot of successful projects have a person who has a who has an idea She was in the driving seas, but it's still an open source thing with a lot happening and I'll be honest I've a lot invested in this code. This this is my baby. So it's kind of sure sure Do let me ask you does it get down to things like British spelling versus US spelling? Because I'm actually okay with British spelling. I caught myself. I actually typed customize today with an S instead of a Z You've really infected me Well, you're just giving me an idea that actually does need to go into the saga and it will be American spelling Because it will because programming APIs are in American So if you don't use American for your variable names Then depending on whether it's a variable name that's come from an API You're just gonna have inconsistencies, right? If you start saying color whether you some of the time and then you use a third-party module or something Which has this the other way you're just gonna break yourself Okay, okay, so it will actually be American But in the documentation, you know in the read-me's and such The interesting thing about okay Basically because all the because everything in coding is in American English I actually think go with the flow rather than you know, I'm Irish therefore. I insist we do it this way No, I go with the path of least resistance. Okay. Well, there's a good example of a discussion. Well, nope This one solves the problem Whether you have an emotional attachment to the you and color. I Mean doesn't matter I prefer it, but that's not the point I Would like the record to show that I have completely adopted companies are Flexions of people. Yeah. Yeah, I've just changed it. I'm just I'm just not doing it the American way anymore I've just moved on but but I'm probably gonna stick with my Z's and My zeds Your Z's yeah, I don't know whether we call them Z's or Z's But I'm terribly inconsistent with them these days because I forget which is which I don't know which I'm supposed to do I don't know which side of the Atlantic. I'm supposed to be on on that one And I have taken your sulfur by the way that I think that was a fair exchange that we say aluminium But we'll spell sulfur the same way Wait, how do you spell sulfur? Well, I when I grew up there was a pH in there. I There isn't oh, yeah, you're right huh, I Believe there was some sort of an agreement That we would spell an aluminium the European way everyone in the world like the IEEE or someone got together and as a swap Sulfur was done the American way. See, I think we I think we say we spell sulfur S. U. L. P. H. U. R Maybe it's you or versus your but it's also it's both. Oh, no it is it's both. Oh, that's awful I never even noticed that before. Oh Well, I definitely threw you off the rails here Okay, so going back so outcomes for the skeleton phase so the UML diagram, which is going to be the Bible for phase two The contribution guides so that we're all singing off the same hymn sheet from day one The configuration files for all of the build described the contribution guides were what's listed in that things like them so stuff like You know the the git policy which at the moment they show under the notes color branching policy But I've just realized that there's no branching because we're doing pull requests So it's just a git policy which we will get to actually today because I've already written the bones of that So it's actually in today's show notes. Well today's discussion and Sort of style guides for for the git commit so again a lot of this stuff is actually already written down below So it will get to it. Okay, and I am certainly open to Pointing at the gaps because I don't know what I don't I don't know what I'm not saying that I should be saying So I'm definitely very open to being told. Well, actually I have a question that you don't answer So that's that's very good feedback at you at this stage. Okay, the other thing that has to be in place is the configuration file So we know our toolkit because we spent the last year learning it all so we know we're going to be using web pack We know we're going to be using JS lint. We know we're going to be using JS doc We know we're going to be using JS. So before we start actually writing the code those config files should be ready So that from day one from the very first moment that one function exists. We should be able to test it document it It should all work so that we're not worried about the plumbing Basically, you lay the foundation and then you build the house So are you gonna have to do all of that yourself too? Well, yeah, because I think that's important to get it sort of all set up right So basically that it will be an empty structure But it will be a structure ready to be filled in Okay, no, but I mean you just you talk about the configuration files So you're gonna have to write the configuration files You're gonna have to create the uml class diagrams. You're gonna have to write the contribution guides Yes, so this is all still the skeleton phase, right? And then the last thing I want to have ready to go is the automation scripts to basically go You know npm run build and it was about the world's boringest build You know a big pile of emptiness, but it should all be ready Right, it should all be ready to go and at that stage then We move on to stage two Which is will the will the build come up with a failed test suite? Um, because it's supposed to fail day one, right? I imagine it will it'll certainly fail some of its tests. Um, it's probably all of them. In fact, yeah That's what it's supposed to do, right? It's supposed to start by failing Yeah, I may leave it with an empty class in which case it'll pass the first test class exists and then fail everything else Okay, but yeah, I mean, yes. Yes. That's the short answer So at that stage when we have a skeleton What will be added around that skeleton then is going to be a direct port So we have the uml diagram So we're going to implement it and we're not going to add new bells or new whistles. We're going to make xkpasswd Work So with the same feature set it has now in pearl we're going to make it work feature for feature Bring it across And I know people are going to have all sorts of ideas for ways to make it better Which is great because what I'll also be opening up is the um The various features in github for tracking feature requests and stuff So we can already start to think about how to make it better But we're not going to actually make it better until we have a working port And at that stage sure 80 percent sure. Let's let's make a little dollar bet here one dollar one dollar Whether any enhancements are are included and I just can't see us Keep it. Okay. I won't take the bet of zero, but I will take the bet of a small n Right, we don't want to get distracted because it needs to actually get to the point where it works before I wanted to get there soon Because the real problem here is that the the website is currently running on an ancient pearl version Right, right one of these days That is going to fall over in a heap Yeah, that version of we're racing the sands of time We really are racing obsolescence Yeah, so we can do what the direct port so and now when you say direct port though Is this is this just pearl to javascript? It isn't the website Correct. It's just the this entire repository is just the module So when this repository is done this repository will have two children It will have one for a new command line version that will probably be slow to arrive and one for a new web interface So those two projects will have as dependencies this one So they will say they will have as one of their dependencies this project So you know the way with npm you can specify your dependencies like you would bring in No j s or something We will be bringing into the web interface the xk pass of the j s module exactly Yeah, this is where I I'm sure I'm going to struggle is is For me programming by stealth got more real when I could see it I could see things happening, you know, I changed the code here. Whoops, that button is lined up against the left side It's supposed to be on the right. I can see what's wrong All right, I press the button and it got the wrong answer, but it but it was visual and so this is going to be all Not visual Nothing will be Yes and no because There is going to be example code because no documentation is complete with that example code So the example code is going to have to exist in some sort of a shape something out on the screen Yeah So it may be a very it may be a very simple interface where they go or a button that says go and an output as opposed to 20 million controls for setting all the different options, but it has to be something to Okay, good to show it working, right? Give me oh, yeah, they're definitely those and the other thing of course is there's nothing to stop you at any point in time Making a project in your git account That says one of my dependencies is xkpass wdjs and you can make the world's fanciest gooey and work away to your heart's content Well and in the future. That's what people can do too That's the point. In fact, that is the hope Right, right desire right because the whole point of making this an open source library is that people do use it So if you have a website and you want to give people a button to say make me a default password Well, why not make some of these nice default passwords? Why why make them all suck or all be impossible to type or say over the phone and you know because that's the big thing Oh, we've set you a temporary password uppercase s lowercase j exclamation point 22 It's horrible to say over the phone versus if I just you know give you a few words and tell you that all is separated by dashes That's actually way more secure and I can say it over the phone People love getting passwords over the phone from me because I use xkpass wd style passwords That's the only way I do it. That's really secure and I was able to write it down. It's like, yeah That was here's how I did it now. I told Bart In text that I was a little worried that we were being Another thing we're racing is whether pass keys are going to be available everywhere on the internet before we're done And so he said oh that means we have infinite time Allison All right and pass keys Think about it this way did The gooey kill the command line No, will vior kill the gooey Which didn't kill the command line no So pass keys are going to become a part of the mix But pass words are going to be a part of our mix in all sorts of different places because what's your fallback going to be What are you going to like it can't be pass keys all the way down? They can provide us an awful lot of Convenient security in an awful lot of places, but it's never going to be pass keys all the way down because even if your pass keys are in one password What's going to protect your pass keys? a password Yeah, the most important password to create in xkpass wd is your one password password Agreed. Agreed. Um, yeah that in your apple id because you have to type that all the time Yeah, people see me typing my one password and it's like wow that's long It's like yeah, but it's actually easy to remember because it's a nice phrase. I won't say what it is But it's it's it's an xkpass wd so password. I have a little image in my head and that was the trick Okay, so so feature for feature of the pro module the javascript most of that Because it's all functioning and it is creating passwords in the way that they need to be created and they all the all your math Entropy calculations and everything. There's really no reason to enhance any of that today Correct because it it works right the problem with the old site isn't the password. It's the ui It's the right right that's where the enhancements have got to come in and of and they obviously will because It would be hard to code it just like it is now It's of what I mean that site was coded before the concept of a mobile phone Capable of rendering a real website existed right at that stage it was wap if you remember that garbage Yeah, exactly. So, yeah, I mean, yeah, the current interface is just not fit for purpose So the okay, so during the structure here Yeah, so during phase two will be implementing the feature for feature Basically the uml class diagram will be translated into actual code That is ultimately the whole point of the direct port pull requests will be open So people will be able to contribute documentation. They will be able to contribute code that follows the uml diagram I will happily take it on because any function that you guys implement That's in the uml diagram that I don't have to implement is less work for me So the uml diagram is the bible and anyone can follow that bible and said pull requests and we will merge them in merge them in The issue tracker will be open So a we can use it to track the bugs we're making as we go because you know there will be And b we can use it to start collecting enhancement requests Sure, we're not going to do them until we have a working port But why can't we discuss them? Why can't we have those conversations? Obviously, you know reason, you know, while people are keen and while people are excited capture it Get it get it written down. We can start triaging them start ranking them. What's the most requested feature? What's going to be priority one? What do we put as our first milestone? We can work on all of that in parallel to writing the code and they can be different human beings So we could have some people doing documentation pull requests. We could have some people writing just a code We could have other people improving the test suite. I mean You don't have to do everything right, right as long as this This is where i'm hoping that our our different skill sets will become valuable where different people are working on different pieces of it exactly exactly and Particularly during phase two here Think of it like a coloring book the uml diagram has drawn all the lines and we just have to fill it in And anyone who can color in any piece is welcome. It doesn't matter what type of piece you want to color in right? We've all of these pieces need to be colored in so get coloring and submit your pull request so the outcome of all of this will be Obviously an es6 javascript module that implements the api in the uml diagram detailed documentation A test suite with full code coverage in other words every function that exists should have a test in fact should have many tests And there will be a package in npm so you can go npm install xk pass of djs So it has to be in the official repository and ready for people to use and then we will consider phase two complete and then we move on To the effectively the indefinite life of the project so maintenance and enhancement Fix any problems that show up deal with any new apis As javascript the language evolves. There are probably going to be things we want to do and you know, whatever es8 brings along We will probably want to put some of that new javascript into the api because I mean if you think about it if we had if we had done this port before promises existed We would do this port very differently Right, so whatever a new philosophy comes along to javascript We'll probably want to bring it into this project over time So that's what I mean by maintenance right code that isn't looked after go stale. It's like bread I like it. I like it. So there's something big missing from this Where does the website come into this? Well, the website doesn't come into this project the website remember is a second project So once part two is complete the website can start It will be a separate git repository Which will have as a dependency this one So it's going to be like a year from now before we get to start building something that we can see what it looks like I don't think so Because a direct port is donkey work more than thinky work So by Easter, I would really like To be worrying about how to lay out dropboxes and things on a web interface Hmm Okay You know once that uml diagram is there coloring in between the lines is a very different thing to Designing something from scratch. You haven't seen how long it takes me to write a single bash script. So Everybody else is faster than I am so You know practice makes perfect. I spend a lot of time running code. I'm pretty quick it Right to me what slows me down is figuring out how to do it But when you're following a diagram you're implementing a known spec it you kind of get into a flow state and it just You know, yeah, I think I think more mature developers definitely do I'll send Dorothy a question on on some code and she'll say hang on Let me let me write you an example And you know like eight minutes later. There's a working functioning class and all this other stuff I'm just like oh geez come on I think I could write a for loop in 15 minutes But I sort of think of it like The first few times I had to write a technical document in technical voice it took me forever You get something that didn't read like it was written by a five-year-old, right? Something that looked like it was written by an it professional trying to communicate with other it professionals That used to take me so long to do up you know a service definition or A Documenting a process or something But now I can just you know someone says oh we need we need a service description for this new thing We're rolling out. Okay. Fine. Yeah. Give me half an error and there you go and it will be It'll be right. It'll read right and with code. It's kind of the same when you do it enough It's like a language If you know what you want to say you can just say it But like I said the really hard part is usually figuring out what you're trying to say Okay so The longer life of the project then is going to be a mix of maintaining it by adding in whatever is needed to keep it current Fixing the the bugs which will definitely exist. We will have a test suite and we will miss things There will be bugs. We will fix them And then there will be the various enhancements that people request and so forth and hopefully that keeps it running You know as a living thing Right responding to people's needs responding to changes And continuing to adapt and evolve as make sense to the people who actually use the code Right, right And I have no idea what people will want because if I did Well, then there wouldn't be any need for if I did I'd be some sort of magician Because that's just not how it works right when you when you put code out there for others to use You have no idea what they'll do. I I like I say I don't know but I promise I'll be surprised I will be your best beta tester That I know for sure you have I can break everything because bugs. Yeah, it's great. I am a savant in that category I have a colleague in work who I value greatly for his ability to break everything I give to Just like every every thing it's like I know I'm pretty sure this is bulletproof I've been hammering out it for weeks, you know five minutes area. What about this? I never realized you could even think of doing it that way. You know, you're right. That completely breaks. Okay back to the drawing board It's a really valuable skill um So I mean that is the most important thing is Is the plan so I have already put a bit more detail into some of the stuff So the first thing I spent some time trying to figure out is the folder structure for the project because I often get very confused When I look at someone else's code like if I go to the uh github page for Something like jQuery I find it very hard to figure out what all the folders mean So first off this repository structure section is going to stay in this read me forever Okay, um Because I really think it's helpful for people to know what the sudden hell all the folders mean and so I've decided to try to name things with a mix of verbosity and standards so Bill there is no standard place to put your build scripts So I called the folder build scripts that is a folder that is going to contain the various scripts that will turn our You know mermaid code into actual pngs We'll make our documentation will run webpack all the various scripts to make the project build will be in that folder it is A pseudo standard that your distribution in other words the thing the finished product Will go in a folder called dist short for distribution So I'm going to keep that convention because it's so universal I Yeah, based on the case of where I'm going. Yeah, it's not perfect. But you know something everyone does it this way So this is this is an example where it's best to be consistent Same with docs First start github likes it that way because your docs folder becomes the web root of your project's web page So that makes perfect sense to me Um doc static then is where the stuff That j s doc is going to copy straight into the documentation without editing is going to go into doc static as the static content for the documentation And in there is going to be a sub folder where all the diagrams go So doc static diagram. So in other words when we take our Mermaid source code the pngs will go into doc static diagrams Hang on uh, your documentation on this doesn't say that doc static is inside docs It's not Oh, you just said it was Okay, you just said it was inside it. Okay No, no, so the content of this folder will get copied into Docs by j s doc. So the docs folder is going to be built by j s doc And the static content gets copied rather than transformed Right, right. Okay Um, so yeah, there's a parallel folder that gets pushed in Uh, s or c is going to be where the source code goes again. You skipped over the diagrams back up So so inside doc static will be a sub folder named diagrams, which is where the pngs will go that are built by the build script Okay Where are the Now the uml diagrams again, though. Oh, okay Yep, because we're doing now for better quarter. Well, no, no you said you said the uml diagrams will be in the build scripts Now the build scripts will create them. So the build scripts are the so the build scripts do the transforming All right, okay So we're getting to the real meat here the source the s or c folder is going to contain the module source code So the most obvious thing that's going to happen is that the build scripts are going to take the content of the source folder and turn it into The module in the disk folder We're going to have a j s doc command that's going to take the content of the source folder and read the doc comments and build The docs and put them in the doc's folder That same j s doc is going to take everything that's in doc's static and just copy it straight into the documentation folder So doc static just get into doc's Okay into doc's yeah And then one of the things in that doc static folder is going to be a folder of diagrams It is the finished completed diagrams because there's a final folder s or c diagrams that's going to contain the mermaid code So the build scripts will take the s or c diagrams to make the png's And the s or c to make The java script Okay, I might need to draw a flow diagram for this because this doesn't make a lot of sense If I look at any one specific thing that you just described I can hold it in my head, but as soon as you move to the next one I've lost it again going wait a minute. Which one's the real one. I might draw a diagram for you Please I could submit a pull request to uh Yeah, absolutely. Well in theory I'll be able to but uh, yeah, okay Oh, yeah pictures is a thousand words. I am very happy to have diagrams created by people I'm usually the one who creates the diagrams for others in work But I it's a lot of work making diagrams So if you want to volunteer for diagram making I will happily because you put fun googly eyes in your diagrams That one you posted for um comments recently in the slack. That was that was a very fun diagram Really clear really obvious and the little googly eyes were just perfect Just for anybody listening I was talking about an automation that had hazel And I wanted to designate that hazel was looking at the folder So I took the hazel logo and put googly eyes on it that made me laugh too. I'm glad you enjoyed that Yeah, but so clear like and that's the point of a diagram and it communicates without words. It worked perfectly So the other thing I spent some time writing up is the contributor and developer resources and guides And the idea here is to lower the barrier to entry as much as I can So the first point is, you know, you're going to need to sign up for a free github account to contribute You can download the code Without anything else, but in order to contribute in some way you are going to need a free github account So there's a link there to the sign-up page if you want to just Download the code and build the project you're going to need to have No js We're always going to we're always going to assume long-term support So if you want to run a more modern version of no js on the long-term support version knock yourself out but If you want to expect this to build without it causing you problems you really should be running The at least the currently supported version of no js And the lts is the least stress way of having the most supported version because it has long-term support It's just you know, it's officially supported for ages. That's that's the joy of lts You're going to need to have some sort of Basically a linuxy type shell and the official word for a linuxy type shell is a posix compliant shell It's a very fancy word Linux and mac you just get them for free as of About two weeks ago windows users now get them as a free out-of-the-box feature 2 through the windows subsystem for linux Which has gone general availability. So it is no longer enterprise only beta feature. It is now generally available I've linked to microsoft's documentation for installing it. It's very straightforward And then you have bash on windows so bash Not zsh Yes, because bash is like a sub zsh is like a super set of bash. So if we target bash then it will work in zsh Oh, okay. So I I wouldn't have to downgrade or I wouldn't have to install bash on a on a mac that's got zsh now No, no, no, it's just running stuff. It's not it's not creating something using some weird thing that doesn't exist in bash Correct. Exactly. Exactly. So Yeah, so basically the reason for using bash is to be more backwards compatible because Anything bash can do zsh can do but that's not true the other way around Gotcha, gotcha. Okay. Good Um, and then if you basically you want to do this stuff yourself You need to be confident enough on the command line to go to a folder and run a command And okay, which is not the words highest ask But if you'd like some help taming the terminal Is this a really fun series to people who have no idea who you've ever heard of have done? I heard it was highly acclaimed Yeah, well, I certainly think it's good. There's actually a book you can download Yes, and thank you, Helma. Um If you would like to go further so you can Do that and you can build the code yourself and you can edit it yourself And you can have your own private version with 20 million new features And you can just do that to your heart's content and that's fine If you'd like to take it to the next obvious step and actually contribute back to the project You need a few more things you're going to need it Um, I don't really care what version it is as long as it's one of the supported versions I don't care what client you use as long as it's you know modern Well, you don't even need a client You could do it from a command line You can hear from the command line You can do it even from the github web interface if you like typing code into a web interface It's not the worst web interface. Yeah. Yeah Um, you need to have a working understanding of markdown really because all of the doc comments are in markdown And all of the documentation is in markdown. So if you're going to be writing a new function I do sort of expect you to write the very very basic documentation of the doc comments So, you know be able to make something bold be able to put in a few bullets or whatever The back takes for a code. That's probably what all you need really, but you know, just the basics of markdown Uh, you're going to need to have a code editor And in an ideal world for your own sanity, it should support markdown and javascript syntax highlighting And if you'd like your pull request to be accepted without me coming back saying please change this this and this Some support for es lint would really help things along because then your pull request will just be right Wouldn't you prefer it be just a requirement that they whatever use has es lint support? I mean do you really want to be in a position of telling having to tell someone? Okay, go fix this this and that you doing the work to write up what they need to fix to make it meet this standard I have maybe once I have a feeling that with helmas with helmas help I can write a github action that will automatically apply es lint wherever possible and only then Basically it would auto reject the pull request with actual useful error messages without me having to do it Oh, okay. Okay Like i'm 90 sure that's easy But i've never done it before and helma keeps telling me github actions rocks and um, okay This is an opportunity for me to be educated or to educate myself I also gather together all of the links I could think of to all of the documentation that might be handy if you're contributing to the project Um, this will expand over time, but for the moment we have javascript no npm js doc our doc dash js doc theme mermaid es lint just Webpack i'm sure i'm forgetting stuff I will append to this list as and when it becomes important Our versioning policy is supremely simple. We're following semantic versioning or semver. There we go I don't have to write the docs link In terms would it be messy in here if I added in um Links to where you these all of these concepts were were, uh taught so for example, you've got Uh documentation for the project's codeliner es lint We could also have a link to the podcast episode where helma taught it to us I was just we could have a link to that Okay I was really hoping someone in the community would volunteer to do that. Um, because you're absolutely right It would be very convenient to have links back to the pbs pages It's yeah without making this look too messy, but it you know But it's it's the first thing we're all going to do is go do a search for mermaid in in uh pbs I I literally just did that search. How did he do that again? Yeah, I'll be doing the same so you're dead, right? It would be very handy to have So you just pop them in brackets afterwards pbs and then the number that'll do it, right? Yeah, yeah, that shouldn't be messy at all. Actually, it should be really helpful In terms of source control policy then Git commits that are going to be merged into main will be titled in line with the conventional commit approach So again, this is a standard we talked about in pbs So I am going to use conventional commits Uh, this right point two here I am going to be the one who gets this wrong so you can all shout at me when I get it wrong But I did a bit of reading a few months ago for I was doing a presentation evangelizing gait in work And I decided to read the best practices for gait and I was horrified to discover I have literally been doing it wrong all along It is a convention that you always use the active voice when you are writing gait commits. You do not say added You say add So you the the comment is not added Documentation for whatever it's add documentation for whatever it's what you will it's what the commit does Not what it did. Why does that matter? That is how and now that I see it if you go to anyone's release notes, they're always in that format So it is sure get best practices. I'm going to obey the best practices and I'm trying to teach myself to do it in all Because it's the best practice. I'm trying to do it everywhere So and I'm going to get this wrong right so so not fixed typos Fixed typos Yeah, yeah So what what that sounds like I'm telling you to do something not that I did the commit is doing it to the code So that's what it's in the active voice Fixing typos No active not present tense. I know it took me a while but Keep an eye on When you see a changelog keep an eye on the tense and it's the active tense and it I didn't notice it. I've been doing it like years of not using the active voice Years and then once I read on the gait website like right from the bloody horse's mouth, you know Um, and okay, this is the best practice and once I knew what it was I started looking for it And I was like, oh look, there it is. There it is. There it is Like I say, I look I've been doing it wrong for years. I will do it wrong At this stage, I've had about 60% of the time I get it right I mean the other 40% I go and edit and then push And sometimes I just push too quickly and then it's too hard to edit and I just started going. Yeah next time Okay But anyway, I you know Say you know do as I say not as I do might be the one here. Anyway Um all contributions are going to come in via pull requests. Um until we get to version 1.0 Uh Basically until we get to the point where you've implemented the uml diagram I'm only going to accept pull requests that implement the diagram So we're moving towards the diagram and I am going to be perfectly happy to merge things That don't pass tests and stuff because we're just filling in we're we're filling in the coloring book So I'm not going to be a stickler and say, oh, you've written a function But you haven't documented no until we get to version 1.0 If it if it moves us towards the target, it's welcome Doesn't matter if it's half a thing or a quarter of a thing if it moves us forward Bring it on bring it on once we get to 1.0 and we have Effectively a working product where we have to be stricter in what gets merged into main So to merge into main it has to be the word I'm going to use is atomic It has to be a complete logical thing, right? So if you're adding a new function Well, you you actually add the whole function its doc comments and its tests, right? If you're bringing in a new thing you bring the thing But an atomic thing can be failing Not once we go to 1.0, right? No, no, no, but I'm saying beforehand. Oh, you're talking about after it's I'm talking about after yeah, yeah before Okay, as long as you're coloring within the lines bring it on That's my analogy I like that so if I've colored within the lines But I didn't color in all of the parts of the of the thing That's okay. That's okay. Bring it in bring it in So I come behind Dorothy Dorothy writes part of the class and or she writes the class and I write the the After she does it I write the test Or I write the test and then she writes it in either way But either one of those things could go in separately, but once it's at 1.0, then it's got to be Holy Yeah, each piece is a whole that makes sense. That makes sense. Yeah And so what do I mean by a whole? Well, all the tests have to pass or it's certainly not going to be merged into main Uh, if you're adding new code that does something new Well, then we need new tests because you're adding a new ability so that should be tested So it should come with it's whatever You know, whatever tests are needed should come if you're only fixing something Well, then there's no need for new tests But if you're adding something new it needs to come with its test If you're adding something new it needs to come with its doc comments, right? So if you change the meaning of an attribute you have to document what's changed If you're adding a new attribute or if you're adding a new function or if you You know, it has to come with its comments because otherwise we don't know what it is, right A function that isn't documented is a mystery meeting. We don't want that Okay and I'm going to want your code to to to be in line with the project style, which is basically going to be defined in the es lint config But ultimately, right the style guide at the end of the day The simplest way to think the style guide is take your lead from the existing content, right? Look up look down if your code looks completely different to what's above you and below you Make it not look completely different. What's above you and below you? Great that ultimately that that's that is the golden rule Um a few little housekeeping things right markdown is a very flexible language So To avoid confusion wherever markdown has multiple options I'd like us to pick one and stick to it so you could use a minus sign or an asterisk for a bullet I would like us to use the asterisks You can use underscores or stars to make things bold. I'd like us to use stars You could use underscores or stars for italics. I'd like us to use underscores because to me star star looks bolder Yeah, and underscore looks softer Um in terms of headings. I would like us to use the pound sign the octa-thorpe For even h ones rather than the other thing where you can have heading colon and then the underline I've never even heard of that. Okay. Good. Great. Then you're not going to Rock Um, and if you're adding a multi-line code block with the three back ticks, please use the language Specifier because that will make syntax highlighting look a lot prettier Yeah, the only reason I know about that if you ever look at the raw files for Bart's Documentation for programming by stealth. You can see how it's done. That's the only reason I know that even existed that it it causes the syntax highlighter to be happy Yeah, and if you leave it out a lot of A lot of markdown editors will guess at the syntax And so if you have a big piece of code, it'll probably guess right, but if you have a one-line code snippet Yeah, you know You as a human would have trouble, right? Is that c or javascript or java? Toss a coin like so just tell it and then it won't have to guess Um There are multiple syntaxes and mermaid basically the one we taught in programming by stealth is the one I'd like us to use There is another syntax that I haven't even told you about I I don't want it Because it's horrible. Okay And If you're using Basically if your editor has es lint enabled Then 99% of the style stuff is just going to work The only thing I would say is if you're picking variable names just look up and look down and Try to keep it in tune with what's there As a general rule, I prefer longer variable names. So they're less Fuzzy, so this is like longer variable names. Yeah um With capital letters for the camel case The camel case it will be unfortunately es lint. Um, oh, we'll make sure of that. Yeah Um Where and then when it comes to writing the doc comments There are two things where j s doc is a bit like markdown. It's a bit too generous in the possibilities Please use at param not at args and please use at returns plural not at return Okay, at return just breaks my head. It's an active at returns. That's an active verb, right? Right and it also goes with at throws Because there is no you can't have at throw it has to be at throws But you can have at return and it just looks so wrong to have at throws and then at return Like no if you if it throws it returns I don't know I shouldn't get so cranky about these things, but that one really does my head and um, anyway, so I've tried you know, I've tried to write it all in this friendly way as I can I you know, please help if There's stuff here. That's You know, that's not sensible Not clear That you think is rude It's basically what I'd like to be is that it's as easy as possible To contribute as constructively as possible Because everyone who contributes something freely to open source That is that is a gift And I want to make it as easy as possible to give but at the same time You know give constructive things so I don't know how best to phrase it, but it's a given to take You've struck the right balance. I think and by setting out expectations up front It's not a surprise later when people like well, I don't want to use two Two spaces. I'm going to use a tab or whatever. You know, I don't want to write an active voice It's like, yeah, but I told you the rules up front. Let's try to let's try to do it I think it's easier to follow a structure than to not like I said and I would agree and I used to be very I used to have My style and I would take my style with me everywhere And that just causes constant friction everywhere And my approach nowadays is If I am joining an existing anything the first question I ask is how are things done here? And I slot in And all of a sudden you become a constructive participant straight away Instead of it being like, oh god, the new guys here. Oh, he's causing trouble And I People if people like having me join a project because I'm not going to be the person who throws a spanner in the works And yeah, it means I'm forever being different, but yeah, okay, so what you know I have gotten over Microsoft insisting that we use Pascal case instead of camel case for variable names in power shell That one took me a while to not get wrong, but I got there. I got there. I can do I can do leading capitals It took me a while Actually, you would love you'd love actually just an aspect of power shell It's all functions are named verb noun And there's a list of allowed verbs that have a meaning So Set has a different meaning to add has a different meaning to create and they're all predefined And so if everyone follows Microsoft's documentation, you get this amazing consistency across projects It's so pleasing. This is verb noun. What does it do to what? Anyway It's a little bonus extra. I like it. I like it. Well, this is exciting. I did notice this is episode 142 So we'll always remember it was almost 42 was 142 was when the project launched And by Easter we're going to have working code. I heard the project manager declared it so Yes, and the fact that I probably have a week's worth of annual leave in the week before Easter is probably why that'll happen So I am I am worried about one thing in this and it's how you are going to manage if you have to do all of the pull requests Because you work for a living and you work long hours and you have important responsibilities and you got a home life and I'm not sure I have to manage all the pull requests. I need to get the skeleton done I want the skeletons in place. I think others can be trusted to manage pull requests because there will be guides I just need to make the guides exist before we can get to that stage. So I actually do think that there is room for a There's like volunteers and there's like dedicated volunteer. So if people want to be dedicated volunteers, I think there's room to have a team of Core maintainers, I guess is the terminology. Yeah, don't don't let me do that I think there are one or two volunteers lurking in the slack who may jump with the opportunity But yes, I actually think that Good good because the worst thing the world would be a bunch of people working on it up early on and you're like Overwhelmed because there's all this stuff coming in and you've got to check it all and see whether it's you know doing anything and And those sit I think that's right. I hate it when I see a repo with with pull requests and they're being ignored That's just you know say no or say yes pick one, right? Right, you sometimes come to a place where it says, you know 98 waiting pull requests. You're like, oh, this might be dead and People want it, which is really sad. Like it's dead, but it's popular Yeah, I hope I hope that does work out in a way that it's it's not all on your shoulders because that would be unfair to you Well, no be fair to you. It's your project But uh, it would be unfair to the people trying to contribute because we wouldn't we wouldn't be able to get there I don't think Precisely precisely. So yeah, I think So hopefully it's december now. I have a fair bit of annual leave saved up I'm hoping the skeleton is done before I go back to work and then if the direct port is done by easter I think we're doing very well and that doesn't seem unreasonable to me Why do it is it so god, we knows what'll happen in it but it seems probably reasonable to me I'm never allowed to be in charge of schedules because I'm always like well, this should take eight minutes seven months later People in work are used to the fact that I work in a unit of a person days Six so how much work is that? I'm saying that's probably five person days and they look at me. It's like A whole week for one person. It's like, yeah Okay, so that'll be done next week. It's like, no No I have many many many demands on my time. You will probably get an eighth of a person So that'll be eight weeks I'm just so glad to hear you say person person time or person hour or person day when I was working. They always called it man hours And there was a there was a schedule once I remember up up on a view graph and at work and it said seven men And I raised my hand being the only female engineer in the organization said so apparently I'm not working on that project And they were like, oh, I'm sorry. I'm sorry. I'm sorry. We'll fix it in the next month It looked exactly the same still said seven men Yeah, I left that organization after that Not because of that one thing that was just endemic, but anyway Times have changed. So that's fun. But this I'm excited Bart. This is this is cool I feel like we're we're not just fixing to make a plan. We've got a plan Yeah, it says project plan. Look it's a h1 and everything All right, Bart. Well, I think we will be we've decided to not Meet wait, do we have one more? No, no, I think this is the last time we wear this hat until next year But we have our security hat, which is a different podcast which we will be wearing again before the year is out Okay, so if anybody's listening this real time Happy holidays and we'll see you in 2023 Indeed, whatever it is you do over the Actually, it's not even the winter for everyone. I was going to say, you know, whatever you do in the winter season And then I thought of poor allister poor allister sitting in the sun Anyway, happy holidays, I think covers it perfectly. So until then lots and lots of happy computing If you learn as much from Bart each week as I do, I'd like you to go over to let's-talk.ie And press one of the buttons over there to help support him He does 98 of the work here I'm just the stooge that listens to him and asks the dumb questions If you go over to let's-talk.ie you can support him on patreon You can donate via paypal or you can use one of his referral links I really hope you'll go over and help him out In the meantime, you can contact me at pod feet or check out all of the shows we do over there over at pod feet dot com Thanks for listening and stay subscribed