202: Using Towncrier to Keep a Changelog - Hynek Schlawack
This is the last of a 3 episode series focused on the changelog. Episode 200 kicked off the series with keepachangelog.com and Olivier Lacan. In 201, we had Ned Bedshelter discussing Skryv. And now in 202, Hinnick joins the show to discuss Town Crier. Town Crier is used by Twisted, Pytest, Pip, Buildbot, and Adders among others.
Brian:So you, you got involved with Town Crier through Twisted. Is that right?
Hynek:Yes. Town Crier grew out of the Twisted's, ecosystem. It was, written by Amber Brown, also known as, Hawk Owl, which I probably don't know how to pronounce. There's way too many w's for my, Middle European tongue to pronounce properly. And, yeah, it started as a twisted tool.
Hynek:And over the years, it got quite widely used, but, it always had a bit of a problem with, not getting enough love, mostly, regarding documentation.
Brian:It's a
Hynek:big problem. But still, it was used by big projects like PIP, for example, is using it.
Brian:Oh, really? Okay.
Hynek:Yeah. Yeah. Or others for that matter. I've been using for a long time.
Brian:And I got I I could noticed it because Pytest uses it as well.
Hynek:Well, there you go.
Brian:Yeah. And but so it is it's on one of those tools of automating the change log. Is that too simple? Or
Hynek:I mean, in a way, it's it's maybe more too general. It's not about automation. It's about avoiding merge conflicts on the change log. That is the sole reason for it to exist. This is the reason why, Blurb exists or Scriff or Reno and what name you all these tools just want to, prevent the situation that multiple people have open pull requests
Brian:Okay.
Hynek:And try to write their changes to the changelog at the same time and just keep having conflicts between those. Because if it's a flat file and the order is the same, then you get conflicts. So these tools allow you to put these changelog entries into separate files that have unique file names, and, you assemble them to a change lock when you release the file release the software, like the next version. And this way, you cannot have merge conflicts on the change lock because the change lock does not exist until you release.
Brian:Okay. Yeah. So there you're not gonna have merge conflicts because everybody's merge has its own fragment or file fragment?
Hynek:Yes. It's called news fragments usually.
Brian:Okay. News fragment. So I was just, like, looking at so that I had something to look at. I've been looking at the Pytest. So in the Pytest repository, there's a change log directory with these fragments in it.
Hynek:Yes.
Brian:Is that is that normal? Is it do I need to name it change log, or I assume that or does Town Crier let me specify what directory it's in? Or
Hynek:Yes. I you can you can configure almost everything. You can you can decide how you call the directory or how to call the file that the that the change log is written to. It's all configurable. And the file format is also not set.
Hynek:You can use, restructure text or you can use markdown. You can use whatever.
Brian:Okay. You can use markdown because I heard some bashing that you couldn't use markdown with.
Hynek:Yeah. Well, people love to bash what they don't know, but, this is the problem is that Town Crier never had great documentation, and this is what I'm working on right now because I want to fix it because this is unnecessary. Like, Duncrier, suffered unnecessarily because it had features that nobody knew about, and I'm trying to change that.
Brian:Yeah. Cool. Well, looks so markdown's 1 that you can you can have, files in markdown. Any other cool features that we might not know about?
Hynek:Well, it it depends what you understand under cool. It's mostly, you have the need that you don't want conflicts on your changelog. And then you decide between the tools that are available, and I think the most common ones are Blurb, which is from the CPython community, which is only made for CPython. So you you shouldn't be able even to use it, so that's right out. Then there's, Reno, which is coming from OpenStack, which has a different philosophy entirely because the fragments stay fragments the whole time.
Brian:Oh, really? Okay.
Hynek:It does assemble a change log, but it doesn't delete the fragments afterwards. This is what Town Crier does. Town Crier and script, which I will talk later about, both when you release an assembly or changelog will delete these fragments. With Reno, they stay around.
Brian:Okay. So the workflow, is similar to script then, or maybe it's all
Hynek:Yes. Maybe all
Brian:of these. So if I I make a change so if I've let's say I've got a bug. I'm fixing a bug. And, and I I have it on a branch, maybe a fork also, but I don't think the tools really care about that, do they?
Hynek:Depends. Mhmm. So Griff cares about, your git branch and your git username. Okay. Reno, I think, doesn't.
Hynek:I don't know that much about it, but Town Town Crier does not. Town Crier cares only about one thing and one thing only, and it's the ID of the pull request. That's the number that you have in the file name. The news fragments have a fixed format, which is the number of the pull request, then a then a dot, and then the type of the fragment. And the types are assembled to groups together.
Brian:Okay. So, like, in, looking at the Pytest stuff, there's, there's a number and it so there's bug fixes, improvements, deprecation, doc. So this is cool. Tri trivial, feature. I guess these are these are not are these defined by Town Crier, or are these can be anything?
Hynek:They can be anything. Those are, they are defaults, and they are clearly not the defaults which they're using here in Pytest. I there's one feature that Townsquare has, and I suspect that's what this trivial thing is that you can define a category which is not printed. And then it just says, also, the following issues or protocols have been closed, and it's just a list of numbers.
Brian:Okay. Well, like, if I were to, like, change something because the spacing was wrong or weird, I I you don't need to list that. So nonfunctional changes.
Hynek:Yeah. Also, there's changes that do not affect the user at all. They are just something for the developers.
Brian:Oh, okay. So it could be even like updating some comments and something that's important, but or refactoring.
Hynek:Exactly.
Brian:Okay. In the so, okay. I'm I'm I'm still I guess I'm still a little confused. So I'm I've got a bug fix, and I'm Yes. Kind of feigning confusion because I really was confused a couple weeks ago, but I've talked to a couple people and starting to understand this.
Brian:But okay. So I've got a check bug fix. I've got, like, let's say, a, a fix for PyDev. So I've I've forked it, and I'm and, and I've got a on a branch, and I have a fix. It's, at at what point do I fill out the the the fragment?
Brian:Because I don't until I in open a merge request, I don't have this file number thing yet. So
Hynek:Yeah. You don't. So either you just look and guess or you open it first and then you add the fragment. This is Okay. Yeah.
Hynek:This is a bit annoying. Like, I usually just, push it, open a pull request, and, add the fragment, and then force push it again so I don't have a, extra commit for it. But this is you can do it however you want.
Brian:Okay. But I could yeah. I could do an extra commit and just push to the pull request. Yeah. Okay.
Brian:Or I tried to pull request to something, and, one of the other maintainers says, nice, but could you fill out one of these, these, news items?
Hynek:Or that. I mean, at this point, there's, different integrations that will do this automatically for you. Town crier has a command for it too. It's called Town crier check, and it will check if, your branch has a news fragment associated with stuff that is not on the main branch. There's also GitHub actions for that.
Hynek:So, this is automated, so it you doesn't have to be always the maintainer to who is gonna pester you.
Brian:Okay. Automated pestering. That's always good.
Hynek:Yeah. It's the best. Nobody takes this personally.
Brian:Yeah. Okay. Okay. But, otherwise, you've got you've got the little file fragment. And and you said the format inside doesn't matter?
Hynek:No. It does not. Okay. And then Also, the the suffix doesn't matter. So you can like, for example, in my own project, I like to have it end in dot rst or dotmd so I can tell.
Hynek:So my editor knows what it is and give me syntax highlighting and everything. But let's follow through that, for example, tone crier doesn't use those file type suffixes. And, I don't know if
Brian:Well, how
Hynek:does it does, but, yes.
Brian:Okay. You said it does it can do, restructured text or markdown.
Hynek:I'm just talking about the file name right now.
Brian:Right. But, if you don't do it by extension, how does it know what you're using?
Hynek:Do you configure it by extension? Care. Like, Town Crier doesn't care at all, because you define a template, which is a Jinja file.
Brian:Okay.
Hynek:And then you define how you iterate over the sections and how you render them into the file. And at no point does Town Crier interpret the data that is restructure text or markdown or something completely different. It doesn't really matter because you can do it however you want.
Brian:Oh, okay. I get it.
Hynek:It's just plain text templating. Nothing else.
Brian:Okay. And so you you really are, within your template defining what order these groups show up in and stuff. Exactly. Okay.
Hynek:And how you iterate like, if you use dashes or asterisks or whatever for, or you can you don't have to use them at all. You can make them, paragraphs or whatever. It's just it's just a template.
Brian:And then, and then okay. So when I and then at the end, when the merge actually happens or I actually, it doesn't matter. Things are merged. A bunch of stuff gets merged in, so we've got a whole bunch of these new news items. And then how does somebody take all of those and turn them into, into the change log?
Brian:Is there, like, a command or something?
Hynek:Yeah. They run town crier build, and that will do all these things. Yeah. It will also get r m the fragments automatically. So it will write the change log and remove the fragments.
Brian:Okay. And the and it since there's probably already a change log there, it, like, will probably, what, just stick it at the top or something?
Hynek:Yes. Either it will stick it to the top, or you can add a marker where it should insert it. So it will it insert right behind the the marker.
Brian:Okay.
Hynek:And if you I probably can have a look at the pytest change log. And okay. I know it's hidden somewhere else.
Brian:Oh, yeah.
Hynek:Right. And, if you look into inside, there is a dot dot town cry release note start, and that's exactly where it will insert the change log for the next release. But that's behind that line and before the next one.
Brian:Okay. And then that stuff isn't something that shows up in the in the printed version or whatever.
Hynek:Well, dot dot is, is a rest comment.
Brian:Oh, okay.
Hynek:But that's invisible by default. So this is something you have to change when you use markdown, but, yeah, it works.
Brian:Yeah. Okay. Well, cool. One of the things that I was curious about so the the the main the main goal of this is is, like you said, to avoid merge conflicts because right. So if we just had the manual, if we just had the change log and people add edited that themselves, one, they don't I mean, that that is is it something that some people do.
Brian:You you just have a instead of a version at the top of their change log, you'll have, like, in development or, unreleased or something like that, and people can add a line. But then if there's multiple people doing that, you have to manually merge those pieces because it's gonna be the same. If you're sticking with the same format, it's gonna be the same lines. Yes. And we did and that's just a pain.
Brian:So, so this makes it easier. So my question really is you're not gonna have that many merge conflicts if it's mostly just you. So would you use something like Town Crier for a project that is mostly just you maintaining?
Hynek:I can answer this question with facts. I only use it for headers. This is the only project where I use it. I am considering to use it with Structlog, but even there, I usually don't have that many parallel, pull requests open that it would make a lot of sense.
Brian:So for for Structlog, so far and I'm guessing it's because you have more more people, contributing to adders.
Hynek:It's pretty Yes.
Brian:Big project. And then, Structlog is is starting to grow, I'm guessing. But, so what do you do in place? If you're not doing, this, are you doing a manual change log? Or, Yeah.
Hynek:Just just regular, change log dotmd and just write it by hand.
Brian:Okay. And when do you do that? Do you do that do you try to do it, like, as you make changes, or do you do it, like, while you're, like, right before release or something?
Hynek:Oh, yeah. Change log entry should always be part of the of the commit that brings the feature, the bug fix. Otherwise, you will forget things, or it's just a it's just a pain in the butt.
Brian:Yeah. Okay. And so it could be a 2 stage thing then. You could like, every time you make a change, you're adding to the change log. But, at a release time, you might wanna go through and edit those and say, well, that's kinda kinda not not important enough to include or something.
Brian:Do you ever take things out?
Hynek:Yeah. Sure. I always before I release these bigger projects, I always also go through the documentation period and just, read the documentation, start to end. So the change log is part of it, and I always find some typos or some unfortunate, phrasings or something. So this is part of my workflow anyway.
Hynek:Really? Yeah. But the aspiration should always be that the change log is ready to release at any time. I really believe that because you lose context. You lose nuance when you wait months until you work on a change log.
Hynek:So
Brian:So you really go I'm gonna come back to this because this is kind of fascinating. You read all of your documentation before a release for a major release?
Hynek:I mean, it's not always 100%, but I usually go through it. I definitely always read the read me and the index pages. That I do always without exception. Okay. Usually, also introductions and the tutorials, I do not read the whole API documentation.
Hynek:That's that would be a lot of reading.
Brian:That's pretty cool, though, because there's those are things that people forget about. Like, and if you change you improve the workflow, for instance, and there's a better way to do things with something, as an initial, like, that's often an improvement that people make is like, oh, this was a little clunky before, and I've made made it the work the the default, what people should do better. But then don't then don't don't update the tutorial.
Hynek:Yeah. Absolutely. Uh-huh. Like, tutorials especially tutorials should always be, read and reread and make make sure that they are correct because it's, like, the first contact for people. And if the tutorial errors out on them, that's not a good starting point for a project.
Brian:Okay. But there so to, back to town crier a little bit. You, oh, I did do see it now that it's I guess I didn't notice before that it was under the twisted, group. So it really is one a twisted project. Is this so you're you're trying to make sure clean up the documentation a bit, maybe add some things that people are not using, or add things that people don't know about.
Brian:Is this Yep.
Hynek:Literally today, I have, submitted like, 5 minutes before we are recording, I've submitted a pull request with a how to about using it together with markdown.
Brian:Okay. It's awesome.
Hynek:Specific specifically for the keep a change log standard. So
Brian:Okay. I was gonna, yeah, ask about that, the keep a change you're you can so you the it fits into the keep a change log standard as well then. You can use SoundCore for that.
Hynek:I mean, there's one tiny problem is that in a keep a change log thing, you usually have a link to the compare URL on GitHub between 2 versions. This is something you cannot do with Soundcore currently because you need to know the previous version. So this but I've just changed it to the link to the tag on GitHub, and I think that's good enough for now.
Brian:Yeah. Those the the deltas are kinda cool, though. I mean, I'm not saying They are. Yeah.
Hynek:This is
Brian:a problem, but it's something that people can manually add to an existing change log if they wanted to.
Hynek:Right.
Brian:And that and you you know the version, so you could you could do the delta. It was kinda neat. We we started doing that in one of the projects I work on, and, and when it's yeah. And it there is some manual bits that we have to do. Like, the automated part, like, we'll that we've had totally, extra script that we've done, but in, to automate what the last version was to stick this this in the line.
Brian:But the, conceptually, you could do that as part of the snippet, I guess, in one of the those little news fragments. If you knew what the next version's gonna be.
Hynek:Good to know. Version is not a problem because the next version, Townsquare will either find out if it's a Python project. Okay. It's gonna read out the thunder in it, or you can pass it as a dash dash version. So the next version is not a problem.
Hynek:This is why, in my tutorial, I do link to the tag. Like, you can, you can, like, click on it, and you get to the tag of the release. The problem is the previous version. I mean, sure, this is a solvable problem. Right?
Hynek:You could start parsing the changelog or something, but then Townsquare would need to understand,
Brian:My my particular version numbers.
Hynek:Not just that, but your changelog format. It would have to start parsing it, and that's a lot more complicated than just writing a Yeah. Template out.
Brian:Right. And and, as we I'm not gonna try to tell people how to do this either, but the for any particular project, it's automatable, if you wanted to, to figure that out. But it always bugs me when they're wrong. So, like like, sometimes we'll like, I had a I just built a project of version 191, and it automatically said what's the difference between, like, you know, dot190 and 1 dot191. But dot 190 actually was a burned version because our build failed, and there were some problems.
Brian:And but it got far enough that it burned the version. And so we could have reused it, but it didn't. And so the real delta wasn't between 19191. It was between 189 and 191. So
Hynek:And that's exactly the problem. Yeah. It's it's really not trivial.
Brian:So Yeah. That's always, like, Google cornering.
Hynek:Better to just tell people to run a substitution over it or something and not just do everything in that. I don't know.
Brian:But, also, I think it's anyway, that that this I'm just kind of fascinated by all this because it's a it's a it's an interesting thing to I'm I'm actually considering doing this on a couple of projects where I really am the sole person, but I forget what I've done. So, so it maybe it's the the answer really on a a solo project is just keep a change lock and and have at the top of it the, like, the thing. But is the thing you the changes you did with with the structure, for instance, like, I fixed a bug or I added a feature or whatever. But, but we still have the merge problem. So if I do this on 2 branches and I don't know which one I'm gonna merge first because I'm working on 2 different problems, I'm still even with one person, I could have a merge conflict.
Hynek:Yes.
Brian:So it might make sense if I'm if that's the my workflow of working on many things at once, it still might make sense to use something like Compression.
Hynek:Absolutely. Also, the fact that it forces you to commit a new fragment a lot with your code is, is also useful. You can enforce it. You can make sure that, you don't forget it.
Brian:Yeah. And, also, the other thing that I that I that came up in one of my other conversations was the, there's commit messages, and those are different than it than these news fragment thing.
Hynek:Oh, good. Yes. Like, this is one of my pet peeves. Like, I have 2 pet peeves about change logs. The one is when a change log doesn't have dates, and my other one is when people just recycle commit messages because commit messages are completely different beast from what I wanna tell the user because the user doesn't care about some implementation details that I've changed for whatever reason.
Hynek:Right? They want to know what changed for them.
Brian:Right. So commit messages for me even I mean, I I I just always assume the the the for me, at least, the, the consumer of a commit message is myself. When I look back on what I did, if I'm confused by something, I could look back on, like, some message. And, also, there it's just one line for a whole bunch of stuff. So it's often not enough, but it gives me a hint of what I was working on.
Brian:So I did these changes because I was fixing bug blah or something or attempting to. But like you said, the, the the change log entry or the news entry should be should be the user. What's the effect on the user? Right? Or possibly if it's a library, the the user is a library or an API user or something.
Hynek:Yes. Still a user.
Brian:Yeah. Okay.
Hynek:I mean, there's this difference is that, also commit messages I mean, different people have different opinions, but the majority of people do that. The commit messages are in a a present tense, like add feature, and change logs are usually in the past tense. And to me, that makes sense because the commit does that. It adds a feature. And the change log is a history that you look at, and you say, okay.
Hynek:This has been added or this is different now.
Brian:Oh, interesting. So instead of like, the the just the tense is I'm thinking about that. Like, I I for a bug fix even, I could just add a ed on it. I fixed a bug. So this version fixed something.
Brian:It's a minor thing, but it's interesting. I never think
Hynek:I'm sure your listeners will send you emails, so I'm sorry for that. But it is the most common thing is that to keep the commit messages in, the present tense. What I've seen too, by the way, which makes a little bit more sense, is that some projects don't use the commit messages, but the the titles of pull requests, which also has the upside that you can edit them until you merge them. Actually, you can edit them later too. So
Brian:Yeah. So this is, like, the the Git using, like, the, there's, like, a GitHub action to to pull together all the merged titles and stuff like that.
Hynek:However they do that. I've just seen it, and I I'm gonna I don't like it because I usually or often have more extensive change logs, like more than one line. Some when I, introduce a new API, sometimes I show an example on how to using the API because I want people to get excited right away, and I don't want to be limited to one line only. But at least it acknowledges the problem that a commit message is is not a message for the user, but for developer and, promotes the pull request title as the as the user facing, user facing information.
Brian:Yeah. I I'm actually just, like, right now looking at your, the change log for struct log because I was curious about the the form format that you use if it's just you writing the pros anyway.
Hynek:Yeah. That's just hand handwritten keep a change log.
Brian:Yeah. And then the, and so your hand, oh, you are doing the little the little compare links because you're handwriting them.
Hynek:Yeah.
Brian:But, but it it's one of the I kinda like it. I mean, your the style is kinda cool. I this is completely different topic, but I just noticed that one of your recent changes on Struct Log is you switch to hatch. Are you involved with the hatch project at all?
Hynek:Not directly, but I'm developing a fairly popular plugin at at this point, which is hatch fancy PyPI readme, which allows you yeah. So the the problem with static packaging in Python, which you we had before, like, with Flit or Poetry, is that your PyPI readme, so the landing page on PyPI can only be either a static string or a a static file. So many projects just use their readme, and it's still at landing page. But I have higher standards than that. I like to extract certain parts of the readme and then and then maybe add the change log of the last release.
Hynek:So, basically, if you come to PyPI and see a release, then you see immediately what are the changes on that release. And this is why I used the setup dot py for a much longer time than I would have looked like, like to do. But now I've written this plugin for hatch, which allows you to say, give me this file, but only from there to there. Then give me this file from there to there, and finally, replace all these relative links by absolute links. And, what what do I know, issue IDs by links to issues.
Brian:That's cool.
Hynek:I like to think so too.
Brian:Okay. Because I was just trying to do, the, so for instance, that's one of the issues I've got. It's the issues I've got is so let's say I've got, a project that's on GitHub already. And so if I link to documentation within the project, it doesn't, it work might work fine on GitHub. But then when the when the readme goes into PyPI, the relative link is just wrong because it's it's not on GitHub.
Brian:It's somewhere else.
Hynek:That's exactly what it's used for. I've added these substitutions because Pydantic 2 o will, use that. It's already merged.
Brian:Okay. And and okay. Cool. So are you involved with Pydantic too, or do you No.
Hynek:I'm not. I'm not. I just got pulled into this by Ofek, the with the maintainer of hatch, and he's running around and helping people to migrate to Hatch. And for projects that are that have, interesting PyPI landing pages, he usually, like, lets them use my plug in. For example, he did this with black too.
Hynek:So yeah.
Brian:So is this plug in available now, or is this something you just Yeah. Sure. Sure. Sure.
Hynek:It's it's already used.
Brian:Okay. So is it under your
Hynek:Yeah. How
Brian:do I find it?
Hynek:I'll go to my GitHub, and there there should be
Brian:Oh, hatch. It's right at the top. Hatch fancy PyPI read me.
Hynek:There you go.
Brian:Okay. This is cool. So I'm I'm kind of, I was a skeptic the first one. So I was trying to, pull pull together it was actually my pie p or pie the talk for pie bay, that I was, talking about, packaging, Pytest plugins, and specifically simple plugins. Like, just like, I I'd like more people to understand the packaging world so that people can share fixtures within projects.
Brian:So if they just have a a cool fixture idea for their project, they can share it. And and I started looking through all the the mechanism, and I the one of the happy things I found was that what the by having all this work fine with pyproject.tomon setup tools, now works, but it's in beta apparently. But, it's I think it I don't think they're gonna throw it away. But then I found out about hatch because it's in the, some of the, the py packaging Python packaging people's documentation, and it's kind of fun. It's a it's not it's a little bit more I don't know.
Brian:How would you've used Flit too before, haven't you?
Hynek:Yeah. So to give you a very simple description, it's Flit with plugins. This is how I would describe it overall. It also has a lot of features that I don't use and, I'm not interested in at all. Like, I don't use the CLI interface at all.
Hynek:I just use hatch link, which is the the build back end. Yeah. And I edit my pyproject.toml files by hand. It has more features. It has basically a talks built in, like and it's called hatch environments where you can define your environments and run commands or whatever.
Hynek:But, I don't need any of that, but it has these extra things. But the parts that I'm interested in is a very, standard conformant build back end maintained, but by an extremely responsive maintainer who is following all new standards and implementing them immediately.
Brian:Okay.
Hynek:And is also very interested in keeping it everything working, well. And, yeah, that's it. These plug ins is was the missing part that, I was missing from Flit.
Brian:The yeah. Well, and one of the the there's some of the other pieces I was missing from Flit too, but the, the the hatch part, one of you you mentioned that it, you don't have you don't use it all. It does more. And And that's actually one of the things I really like about Hatch is it's not an environment that imposes a philosophy on you. It's got
Hynek:Exactly.
Brian:It's a tool chest. You can use the tools that you want, and you don't have to use all of them. And I
Hynek:absolutely lightweight, and it's also very robust. It I in the time I've been using it, I never ran into a legit bug, which I cannot tell sec which I cannot say about other popular packaging solutions that shall not be named.
Brian:So we kinda got got off on a tangent about Hatch, but I do encourage people if they if they're unhappy with their current packaging things, check out my talk and also Hatch because Hatch is cool. So is there so I will I'm looking forward to looking at your your, documentation on how to do markdown with, down prior because I I that was gonna be a deal breaker for me. I'm like, I don't wanna learn restructured text. Too many years in markdown, and and I know that there's limitations. I know that that restructured text does things that markdown just can't, and I guess I'm okay with that.
Hynek:That's not really true, by the way. So people conflate restructured text with sphinx, and, it's mostly sphinx that has the cool features. And you can use sphinx with markdown too just fine by using the amazing, amazing Mist extension.
Brian:Okay.
Hynek:Did that just blow your mind?
Brian:Well, I knew about Mist, and I played with it a little bit, but I thought that a lot of the stuff that, like, pulling in code snippets and stuff like that, I thought that you couldn't do that in markdown, but you could do it in
Hynek:you absolutely can. The only caveat is that the markup in your docstrings for now has still to be restructure text.
Brian:Okay. Well, to it's worth it for me to try to figure that out, so I'll have to play with that.
Hynek:It's getting less and less. Like, it's it's really good.
Brian:Okay. And this is through the Mist, project that allows that makes that work?
Hynek:Yes. They they're using basically code blocks to add those features on top of markdown, and it works fine. Like, there's a few rough edges, but to me, that's worth it if I because I really like to style my links, and it's so mind boggling to me that I cannot italicize a link. It's so
Brian:But you you can with restructure text? Is that
Hynek:You can't. You absolutely can't.
Brian:Okay. Interesting. Well, gosh. I always learn so much when when we talk. This is pretty neat.
Brian:Any other cool light okay. So hatch is not awesome. Mist is awesome. Actually and I I haven't used struct log before. I played with it, but I I actually think that I have a use case for it now.
Brian:So I I might be adding a struct log to 1 on my project.
Hynek:Well, I'm very happy to hear that.
Brian:But, you're one of the I don't know if I've ever I've asked you this before, but I may have. You're kinda maintaining a few projects that are used a lot. Is this a how much and you also have a day job and a life. So how much time is spent on, like, open source stuff?
Hynek:Oh, this really depends. So I have this arrangement with my employer that I may use, like, 20% of my time on relevant open source work. And I'm saying relevant also because all the projects that I maintain, we also use internally. So that's one thing. Secondly, I cannot answer these questions right away because I work in binges, basically, on everything.
Hynek:So right now, I spend a lot of time on getting tone crier into shape because I'm very bad at multitasking. And, for me, it's better to just spend one day on working on one thing and another day on another thing and not do 3 things per day and alternate between them. So, yeah. But the answer to your question really is about 20%. And, it's not like like okay.
Hynek:Address is used a lot, but it's also a very major project. So it's not like we have to work on it, 247 to, make it work to keep it working.
Brian:Yeah. Okay. I have one of the things that I've that I've hit is, at made at, like, other major versions. Like like, for instance, at when does Python 310 or 311 or a different Python version comes, you have to you have to add tests to make sure that your your projects are being tested on the new versions, but then also may have to make some changes. Does does that ever hit you, or has it not really happened anymore?
Hynek:With track lock mode really, with address every single time. Literally every single time. It's mostly around the code that, does our slots magic. So you can use slots, something the data class is now added to in 3.10, but it used to be an others only feature. And you cannot add slots to a finalized class in Python, so you have to do some tricks.
Hynek:And once you start doing these tricks, you have to do other tricks so other things keep working, and these corners really like to break.
Brian:Okay.
Hynek:And they broke again for 3 for 3 11. But, yeah. We so far, we always managed to get it working.
Brian:Okay. Did so do you wait when, when do you start working on something like that? Or do you work on do you have a test that runs against, just mainline Python?
Hynek:So at Adders, it's usually that, at some point, we get approached by, by, what's this called? Lin by some Linux distributions, usually Red Hat, because they are packaging Python earlier and testing the packages they package against the new Python. So they run into these problems quite fast.
Brian:Oh, cool. So you don't have to be proactive. You got somebody else, like,
Hynek:or you I would I would like, I am proactive, but not that early. I usually wait into the into the betas or maybe into the r c's before I start, working on that. Definitely, not in the alphas. And I'm I think that, Radahead usually always already starts in alphas. That's too early for me.
Hynek:It's too broken.
Brian:Okay. But RC is whether they come out, like, 3 3 months ahead of time or something? Or,
Hynek:I don't know the numbers anymore, but we are on RC 2 right now.
Brian:Okay. So, address is working great with the Python 311?
Hynek:Yes. It does. Okay.
Brian:Cool. The the thing that gets the the only that hits me occasionally is, so I've got a couple a, well, a Pytest plugin. I've got a few Pytest plugins, but one of them that actually is, kinda naughty and, uses internals of Pytest. And that's that's so I gotta test it against the new stuff all the time because it might break. And for a while, I needed some help because, so, Pytest for a while was straddling Python 36, and earlier, I think it did 35 for a while.
Brian:Pytest now is 37 and above, I believe. And, and that was good because there were some there was, that the silicon I had had had, like, a different, had to support like, it had code that was, like, switched on which Python version, and I I hate having code like that in my code. So, luckily, I've it's that's that's gone out now. But, but but because well, actually, when when I was
Hynek:come back, by the way.
Brian:Is it gonna come back?
Hynek:Yeah. It's affected. It's it's for me to say I hate it. I'm so happy when I drop a version and just, remove such a branch. But it comes to a new version.
Hynek:And, for example, now when you add 3.11 and you use TOML so, of course, you can always depend on TOML kit, but it's much nicer to use, the TOML lib, which now came into the smart library. Yeah. So now welcome to, ifsys version info, smaller, 3 3 comma 11.
Brian:Okay. But every time I have to do that, one of the issues that comes up is now my coverage is not is my code coverage isn't complete unless I combine coverage. So you've got an article on I think it's you that has an article on combining coverage, for multiple, how to, basically, how to do that. And so I just have it bookmarked, and I'm like, whenever I need to do that, I'll go read that again. I mean, I mean, I've got done it enough times, but, but it is, it's kinda cool, to have that resource, so please don't take that down.
Brian:Anyway, Yeah. Kinda getting off in the weeds now, but, yeah, I guess, I'm super glad that I we had a chance to talk. I'm interested in Town of Priore. I think that I think that Town of Priore is less scary than I thought it was. When I first, when you first look at it, it's like there's all these numbers and the special snippets and how does it work, but the workflow of I just you just add this file snippet, and then I've got a template.
Brian:So there there's some setup work that I have to do, but Yes. But the rest of the workflow isn't tons for your day to day life. Right?
Hynek:No. Your day to day life is literally just creating the snippets. You can use TownCrier for a 2. There's a TownCrier, create create and then, for example, dash dash content, and then you can write the code right right in there or dash dash edit, and it will start an editor. And you you, fill out your snippet, and you're done.
Hynek:So for for day to day editing, it's absolutely no problem at all. The only annoying thing is that you have to open a pull request first to know the number for this for the new fragment. But other than that, it's
Brian:Okay. So if I do it like a Townsquare create, is it gonna ask me for the merge number or something? Or
Hynek:Yeah. You pass it as a as an argument. So you say TownCry create, 42 dot bugfix.rst or something like that.
Brian:Okay. Okay. So I think I might play with it just to even on single projects just to see because the, I think it would be better if more people use things like, Town Crier and or Scriv or whatever works for people's, you know, mind state. The I do kinda I'm kinda leaning towards, so there's some projects that don't keep a change log in the repository. They keep it as a, just it's just a release note on GitHub since GitHub does release notes.
Hynek:Yeah. They usually use the commit messages then. You can, say, automatically create change log, and then it just uses the commit messages. As we've established before, this is not great for users.
Brian:But it also doesn't live with the code. So if I clone the code at that
Hynek:Well, it's it's a commit messages, so it's part of Git. Right?
Brian:Yeah. Okay. So I can do a git so I so I could do a git log and see those anyway.
Hynek:Yeah. That's what it does. That's literally what it does. Nothing else. This, release thing.
Brian:Oh, yeah. I don't that's that's that's horrible. I don't wanna do that.
Hynek:Yeah. Don't.
Brian:So I think this yeah. Anyway, I'm I'm glad you are on the I'm glad you're on the case of, trying to make, kind of polish up the documentation and the onboarding a little bit with that.
Hynek:I would love if you would have a look at the pull request, which I opened just, tonight. I mean, it's it sounds like it was written for you. So feel free to give some feedback if anything is unclear, and we can improve it further.
Brian:I love being the major customer. I'll I'll definitely check it out. Thanks. And if I, have any questions, I'll, I'll just, I'll ask. So thanks a lot.
Brian:And I'll let you, enjoy the rest of your evening, and we'll talk later.
Creators and Guests
