Transcript
[0:00] Music.
[0:07] Well, it's that time of the week again. It's time for Chit Chat Across the Pond. This is episode number 755 for December 10th, 2020, 2022.
And I'm your host, Alison Sheridan. This week, our guest is Bart Bouchot, 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 I'm suffering too.
Oh, oh, Wuggums. 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, toques, 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 yeah, we used to have shorts on. I was like, yeah, but my legs are really warm. Well, we are this week in weather. We're going to have to kick in. It looks like we're going to. It's an exciting week.
I think it is. So we are kicking off the official project to migrate the Pearl XK Possibly D module, I'm not going to say its name because it's too difficult to say, to a JavaScript module, which I'm going to call XKPassWD.js.
[1:37] 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.
[1:48] Steve Gibson's idea of basically repeating the same character over and over again to give you length for free with the concept of XKCD style wordy passwords.
And in reality, the only presets I ever ended up using were ones that didn't repeat things because most, sorry, a lot of really naive password managers are like, Oh, you're repeating something. Your password must be insecure and they stop you.
Oh, okay. So the repetition thing doesn't work. So actually why bother pretending the haystacks are there?
No, this is purely inspired by XKPassWD. So let's just go with that. I guess the long part could have come from haystacks, but it was just too hard to say HSXK.
Those four letters just don't work together. So this makes me really happy. to its XKPassWD.js.
[2:37] 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 Git repository exists. That's probably the biggest thing. And I've also put quite a bit of work into an initial readme, 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 where I'm going to build out a project skeleton.
And to be honest, simply creating the repository and this initial readme is part of that building out the skeleton.
So while we're in the skeletony phase, it's going to be basically me arranging all the furniture and preparing for the party, effectively. preparing to host guests.
So the big outcomes that need to be done 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.
[3:41] 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 bring it into the house first.
Exactly. Don't walk in with your dirty shoes into a clean house. Let'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, our get branching policies, our style guides for Git commits.
Basically figure out exactly how we'd like to run the project and try to have it all all documented in a friendly, obvious, easy to follow way.
So, cause 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'm just asking 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.
[4:46] To flow naturally that we do things right. I'm going to give you an analogy that really says why this is such a great idea. In the olden days.
[4:57] Before Christ was born, I used to draw, do drafting with a pencil or sometimes a pen on mylar, and you know, on a big old drafting board, and 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 your parts that would say like bond per HP 8-5.
That's the one I always remember 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 100 years old and I don't ever want to change my ways.
And I looked at it as 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 frees 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 going to 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 spaces in and it'll make it tabs if that's what you want or vice versa.
I think.
Yeah. That's what Hellman tells me anyway.
[6:20] Oh no, well we're going to be using JSLint. So there's going to be a JSLint config file in the project. So your editor, if it's JSLint aware, will pick that up automatically.
And it means that if you're using any of the modern editors, it should just work.
Right. 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 in theory, in the big picture, we don't care. We want it all just to be consistent. And now you say we in some of these sentences, and I suspect that it's mostly I as in Bart,
we'll be making these rules. But perhaps with a an appeals process.
Oh, definitely. I mean, I will. But you have 51% of the vote, right?
[7:19] I guess I'll do a Mark Zuckerberg on it and say that I have the magic extra share. You know, my old boss, Bart, always said it's a democracy, but I have 51% of the vote.
OK, we'll go with that then. But no, I'm completely open to, you know.
[7:36] Any sensible argument will always find an ear with me. But if your argument is because I have an emotional reason I want to do it this way,
you're less likely to succeed. Right, right. But if it's practical and it solves some problems, and 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, nothing gets done.
I believe the common phrase is benevolent dictator in the software world. The Linus Torvalds in the Linux kernel. And there's one guy who led, was a Python for ages, a Dutch guy who then retired and caused chaos.
[8:16] It's a lot of successful projects have a person who has an idea. She was in the driving seat, but it's still an open source thing with a lot happening.
And I'll be honest, I have a lot invested in this code. This is my baby. So it's kind of sure. Sure.
Sure. 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 customized 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.
Oh, it will? 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 going to have inconsistencies, right?
If you start saying color with a U some of the time, and then you use a third party module or something, which has the other way, you're just going to break yourself.
Okay. Okay. So it will actually be American.
[9:15] But in the documentation, you know, in the read me's and such, the interesting to think about. Okay.
[9:21] Basically, because all the, because everything encoding is an American initiative, I actually think go with the flow rather than, you know, well, I'm Irish, I insist you do it this way.
No, go with the path of least resistance.
Okay. Well, there's a good example of a discussion. Well, no, this one solves the problem.
Whether you have an emotional attachment to the you in color.
I mean, I kind of prefer it, but that's not the point. I would like the record to show that I have completely adopted companies are plural. Reflections of people. Yeah.
Yeah. I've just changed it. I'm just not doing it the American way anymore. I've just moved on. But I'm probably going to stick with my Z's and my Zeds.
Your Z's. Yeah, I don't know whether we call them Z's or Zeds, 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 Sulphur, by the way, that I think that was a fair exchange that we say aluminium, but we'll spell Sulphur the same way.
[10:22] Wait, how do you spell Sulphur? Well, when I grew up, there was a PH in there.
[10:29] I there isn't? Oh, yeah, you're right. Huh. I believe there was some sort of an agreement that we would spell an anemone in 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 say we spell software S-U-L-P-H-U-R.
[10:49] Maybe it's you versus Eeyore. Oh, but it's also, oh, it's both. Oh no, it is. It's both. Oh, that's awful. I never even noticed that before.
[10:58] 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.
Describe the contribution guides. What's listed in that?
That things like. So stuff like, you know, the, the Git policy, which at the moment they show the notes call it a 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.
[11:39] Today's discussion and sort of style guides for, for the Git commits. So again, a lot All of this stuff is actually already written down below, so we'll 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.
Okay. 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 actually 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 Webpack.
We know we're going to be using JSLint. We know we're going to be using JSDoc. We know we're going to be using Jest.
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.
[12:32] It should all work so that we're not worried about the plumbing.
[12:36] Basically, you lay the foundation and then you build the house. So are you going to 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.
[12:52] But it will be a structure ready to be filled in. Oh, okay.
[12:57] But I mean, you're talking about the configuration files. So you're going to have to write the configuration files. You're going to have to create the UML class diagrams.
You're going to have to write the contribution guides.
[13:09] 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 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 build come up with a failed test suite?
Because it's supposed to fail day one, right?
[13:39] I imagine it will. It'll certainly fail some of its tests. 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, yes, yes, it'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 xk pass wd work.
So with the same feature set it has now in Perl, 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 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.
[14:42] And at that stage, 80% sure. Let's make a little dollar bet here.
$1, $1, whether any enhancements are included in, I just can't see us keeping doing that. Okay, I won't take the bet of zero, but I will take the bet of a small N.
We don't want to get distracted because it needs to actually get to the point where it works before. I want it to get there soon because the real problem here is that the website is currently running on an ancient Perl version.
And one of these days that is going to fall over in a heap.
And that version of Perl is getting... We're racing the sands of time. We really are racing obsolescence. Yeah.
So I really do want the direct port. So... And now when you say direct port though, is this, is this just Perl 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.
[15:52] 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 Node.js or something.
We will be bringing into the web interface the XK passively A.J.S. module. Exactly.
Yeah. This is where I'm sure I'm going to struggle 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 pressed the button and it got the wrong answer, but it was visual. And so this is going to be all not visual.
Nothing will be.
[16:37] 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. Spit something out on the screen. Yeah.
So it may be a very, it may be a very simple interface where they go with 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.
[17:00] Okay, good. To show it working, right? You can give me hope. So yeah, there definitely is.
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 XKPassWDJS and you can make the world's fanciest GUI 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. The 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 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. Whereas if I just, you know, give you a few words and tell you that all separated by dashes, that's actually way more secure. And I can say it over the phone.
People, people love getting passwords over the phone from me because I use execute passable D style passwords.
That's the only way I do it. That's really secure. And I was able to write it down.
I was like, yeah, that was the point. Here's how he 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, Alison. All right. Pass keys.
[18:25] Think about it this way. Did the GUI kill the command line? No. Will Vior kill the GUI, which didn't kill the command line? No. So pass keys are going to become a part of the mix, but passwords 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... 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.
[19:06] Keys? One password. Yeah, the most important password to create in XKPassWD is your one password password. Agreed, agreed. Yeah. That and 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 an XK password. You do saw a password. I have a little image in my head and that was the trick.
Okay. So feature for feature of the Pro module to JavaScript, most of that.
[19:40] Because it's all functioning and it is creating passwords in the way that they need to be created and all your math entropy calculations and everything, there's really no reason to to enhance any of that today.
[19:51] Correct, because it works. The problem with the old site isn't the passwords, it's the UI. Right, right.
That's where the enhancements have got to come in. And they obviously will, because it would be hard to code it just like it is now.
That site was coded before the concept of a mobile phone capable of rendering a real website existed. At that stage it was WAP, if you remember that garbage.
Yeah, exactly.
Yeah, exactly. So yeah, the current interface is just not fit for purpose.
So during phase two, we'll 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 send 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? Absolutely no reason. People are keen and people are excited. Capture it!
[21:21] 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 are 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 can 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 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.
Doesn't matter what type of piece you want to color in, right? We have 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 xkpassive.dejs.
[22:43] It has to be in the official repository and ready for people to use and then we will consider phase two complete. No one to the effect of the indefinite life of the project so maintenance enhancement fix any problems that show up deal with any new api's.
As javascript the language of all the store probably going to be things we want to do in a whatever yes. 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 done this port before Promises existed, we would do this port very differently.
Right, right. So whatever new philosophy comes along with the 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 goes stale. It's like bread, right?
You need to keep alive. 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.
[24:01] So it's going to be like a year from now before we get to start building something that we 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 drop boxes and things on a web interface.
[24:27] Okay. You know, once that UML diagram is there, colouring 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.
[24:45] You know, practice makes perfect. I spend a lot of time running code. I'm pretty quick at 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, you kind of get into a flow state and it just, you know, Yeah, I think, I think more mature developers definitely do.
I 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 of a sudden someone's just like, oh, jeez, come on.
[25:19] I think I could write a for loop in 15 minutes. I sort of think of it like.
[25:26] The first few times I had to write a technical document in technical voice, it took me forever to 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 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 hour.
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. Like I said, the really hard part is usually figuring out what you're trying to say. Okay.
[26:18] 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 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? Was responding to people's needs, responding to changes and continuing to adapt and evolve as makes sense to the people who actually use the code.
Right. Right.
[26:56] Um, and I have no idea what people will want because if I did, well, then there wouldn't be any need for it. If I did, I'd be some sort of magician.
Cause 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. 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. I can break everything. Cause bugs. Yeah, great. I'm a savant in that category. I have a colleague in work who I value greatly for his ability to break everything I give to him.
Just like everything is like, no, I'm pretty sure this is bulletproof. I've been hammering at it for weeks, you know, five minutes there. Yeah, 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 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 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 readme forever.
[28:18] 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 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 mermaid code into actual PNGs, will 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 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.
[29:08] Yeah, based off 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. For a start, GitHub likes it that way because your docs folder becomes a web root of your project's web page. So that makes perfect sense to me.
Docs static then is where the stuff that JS doc is going to copy straight into the documentation without editing is going to go into docs static. as the static content for the documentation.
And in there is going to be a subfolder where all the diagrams go. So doc static diagrams. So in other words, when we take our mermaid source code, the PNGs will go into doc static diagrams.
Hang on. 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 folder will get copied into docs by JS doc. So the docs folder is going to be built by JS doc and the static content gets copied rather than transformed.
Right, right. OK.
And so, yeah, it is a parallel folder that gets pushed in. SRC is going to be where the source code goes. Again, you skipped over the diagrams back up.
[30:30] So, so inside doc static will be a subfolder named diagrams, which is where the PNGs will go that are built by the build script.
Okay. Where are the UML diagrams again? No, okay. The UML diagrams because we're doing now for better quarter.
Well, no, no. You said the UML diagrams will be in the build scripts.
No, the build scripts will create them. So the build scripts do the transforming. So we're getting to the real meat here.
The src folder is going to contain the module's 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 dist folder.
We're going to have a jsdoc 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 docs folder.
That same JS doc is going to take everything that's in docs static and just copy it straight into the documentation folder.
So docs static just gets into docs. Into docs, yeah.
And then one of the things in that docs static folder is going to be a folder of diagrams that is the finished completed diagrams because there's a final folder, src diagrams, that's going to contain the mermaid code.
[31:49] So the build scripts will take the SRC diagrams to make the PNGs and the SRC to make the JavaScript.
[31:59] 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.
[32:15] Please. I could submit a pull request to... Yeah, absolutely. Well, in theory I'll be able to, but yeah. Okay.
[32:25] 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 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 comments recently in the Slack. 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. That's the point of a diagram, 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.
[33:17] 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 Node.js. We're always going to assume long-term support.
So if you want to run a more modern version of Node.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 at least the currently supported version of Node.js.
And the LTS is the least stress way of having the most supported version because it has long-term support.
[34:06] It's just, you know, it's officially supported for ages. That's the joy of LTS. You're going to need to have some sort of, basically a Linux-y type shell. And the official word for a Linux-y 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 too through the Windows subsystem for Linux which has gone general availability.
So it is no longer an 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 superset of bash. So if we target bash, then it will work in zsh.
[35:01] Oh, okay. So I wouldn't have to downgrade or I wouldn't have to install bash on a Mac that's got zsh now.
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 basically the reason for using bash is to be more backwards compatible, because anything I think bash can do as ESH can do but that's not true the other way around.
[35:28] Gotcha. Gotcha. Okay. Good. And then if you basically, if 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.
Okay. Which is not the world's highest ask, but if you'd like some help, Taming the Terminal is a really fun series to people who have no idea who have ever heard of have done.
I heard it was highly acclaimed.
[35:52] Yeah, well, I certainly think it's good. It was actually a book you can download. code. Yes! Thank you, Helma.
[36:01] 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 Git. 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.
[36:33] You could do it from the command line. Or you can use it 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.
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 in 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 just the basics of Markdown. 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 ESLint 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 ESLint support?
[37:39] Because 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 the standard?
I have maybe once I have a feeling that with Helma's help, I can write a GitHub action that will automatically apply ESLint wherever possible and only then basically would auto reject the pull requests with actual useful error messages without me having to do it.
Oh, okay.
[38:09] Okay. I'm 90% sure that's easy, but I've never done it before and Helme keeps telling me GitHub actions rock. So, erm, okay.
Opportunity for me to be educated or to educate myself.
[38:21] I also gathered 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. This will expand over time but for the moment we have JavaScript, NoNPM,
JSdoc, R, Doc-JSdoc, The, Mermaid, ESLint, Jest, 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. Would it be messy in here if I added in links to where you these all of these concepts were taught?
So, for example, you've got documentation for the projects code Linter, ESLint.
We could also have a link to the podcast episode where Helmut taught it to us.
I was just hoping we could have a link to that.
Okay.
[39:22] I was hoping someone in the community would volunteer to do that because you're absolutely right it would be very convenient to have links back to the PBS pages.
Yeah, without making this look too messy. But it's the first thing we're all going to do is go do a search for mermaid in PBS. 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. pop them in brackets afterwards, PBS and then the number. That'll do it, right?
Yeah, yeah, that shouldn't be messy at all. It should be really helpful.
[39:55] 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.
[40:10] And this is 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 Git in work and I decided to read the best practices for Git 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 Git commits. You do not say added, you say add.
[40:44] So 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.
[41:05] 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.
[41:24] Yeah. So what, what? That sounds like I'm telling you to do something, not that I did something. The commit is doing it to the code. So that's why it's in the active voice.
[41:33] Fixing typos? No, active, not present tense. I know it took me a while, but keep an eye on when you see a change log, 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 GATE website, like right from the bloody horses, man.
And 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.
I guess I look, I've been doing it wrong for years. I will do it wrong at this stage. I'm at about 60% of the time I get it right.
And then 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 sort of go, yeah, next time.
[42:26] OK. But anyway, you know, do as I say, not as I do, might be the one here. Anyway, all contributions are going to come in via pull requests.
Until we get to version 1.0, basically until we get to the point where we'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 filling in the colouring book. So I'm not going to be a stickler and say, oh, you've written a function, but you haven't documented it. No, until we get to version one point zero, 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 one point zero 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, where you actually add the whole function, it's doc comments and it's tests.
Right. If you're bringing in a new thing, you bring the thing.
But an atomic thing can be failing.
[43:48] 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. Just, you know, as long as you're coloring within the lines, bring it up, right?
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 thing, that's OK.
That's OK. Bring it in, bring it in. So I come behind Dorothy, Dorothy writes part of the class and 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. Either one of those things could go in separately, but once it's at one point out, then it's got to be a 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.
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 its 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 tests.
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?
[45:14] A function that isn't documented is a mystery meet and we don't want that. And I'm going to want your code to be in line with the project style, which is basically going to be defined in the ESLint config.
Ultimately, 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. Look up, look down. If your code looks completely different to what's above you and below you, make it not look completely different to what's above you and below you.
[45:48] Ultimately, that is the golden rule. A few little housekeeping things. 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.
In terms of headings, I would like us to use the pound sign, the octothorpe, for even H1s rather than the other thing where you can have heading colon and then the underline.
I never even heard of that. Okay. Good! Great! Then you're not going to do a rock.
And if you're adding a multi-line code block with the three backticks, please use the language specifier because that will make syntax highlighting look a lot prettier.
[46:52] 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 causes the syntax highlighter to be happy.
Yeah. And if you leave it out, 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, eh, you know, you as a human would have trouble, right? Is that C or JavaScript or Java? Toss a coin. Just tell it and then it won't have to guess.
[47:32] There are multiple syntaxes in 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.
[47:42] I don't want it because it's horrible. OK. Um, and if you're using basically, if your editor has ESLint 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. I like longer variable names.
Yeah. Um, with capital letters for the Campbell case. The Campbell case will be unfortunately ESLint.
Um, ESLint will make sure of that. Yeah. Um, good.
Where, and then when it comes to writing the doc comments, there are two things where JS 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.
[48:37] Okay. Um, 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 it throws, it returns.
I don't know. I shouldn't get so cranky about these things, but that one really does my head in. Anyway, so I've tried, you know, I've tried to write it all in as friendly a 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...
[49:41] You know, give constructive things. So I don't know how best to phrase it, but it's a given a take. You've struck the right balance, I think. And by setting out expectations upfront,
it's not a surprise later when people are like, well, I don't want to use two spaces. I'm going to use a tab or whatever. You know, I don't want to write in active voices. Like, yeah,
but I told you the rules upfront. Let's try to, let's try to do it. I think it's easier to follow follow a structure than to not, like I said.
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?
I slot in and all of a sudden you become constructive participant straight away.
Instead of it being like, Oh God, the new guys here. Oh, he's causing trouble.
[50:41] And people, 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 PowerShell.
That one took me a while to not get wrong, but I got there. I got there. I can do leading capitals.
[51:12] It took me a while. Actually, you would love actually just an aspect of PowerShell. It's all functions are named verb noun.
[51:23] 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. That'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. It 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 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.
Cause you work for a living and you work long hours and you have important responsibilities and you've got a home life.
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.
[52:37] 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 volunteers.
So if people want to be dedicated volunteers, I think there's room to have a team of.
[52:53] 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 at the opportunity, but yes, I actually think that Good, good.
Because the worst thing in 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 doing anything and those sit.
I think that's, I hate it when I see a repo with pull requests and they're being ignored. That 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 and you're like, oh, I think this might be dead.
And people want it, which is really sad. Like it's dead, but it's popular. Oh, yeah, I hope that does work out in a way that it's not all on your shoulders because that would be unfair to you.
Well, no, it'd be fair to you. It's your project, but 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. 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. Mind you, it is IT. So God only knows what will happen in IT. But it seems perfectly reasonable to me.
[54:16] 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 person days. It's like, 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.
[54:36] Okay, so that'll be done next week. It's like, no, no, because 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 time or person hour or person day. When I was working, they always called it man hours.
And there was a schedule once, I remember, up on a view graph 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. And the next month it looked exactly the same. Still said seven men.
Yeah. 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?
[55:46] No no this is the last time we wear this happen to next year but we have our security hat which is a different podcast which will be wearing it for the year is out. Okay so if anybody's listening this real time happy holidays and we'll see you in twenty twenty three.
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 Alistair, poor Alistair sitting in the sun.
[56:15] Anyway, happy holidays, I think covers it perfectly. So until then, lots and lots of happy computing.
[56:22] If you learn as much from Bart each week as I do, I'd like you to go over to let'sdashtalk.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 dash talk dot 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 feed or check out all of the shows we do over there over at pod feed dot com. Thanks for listening.
[56:57] Music.