@regis @nedbat So it looks like the changelogs won’t be put in place, right? Is that something that we’ll still look into doing differently (maybe by having someone review PRs regularly, and ask questions there?) – or is the high level plan for the release workgroup changing as a result?
Yes @antoviaque, the question of having changelogs was really the crux of the conversation we had. Everyone in the working group agrees that we need them badly, to the point that I wouldn’t want to manage another Open edX release without them. But I’m at my wit’s end when it comes to pushing for this idea. I have tried formulating this idea in many different ways, both orally and in writing. As Ned says, it pains me that the idea of changelogs remains controversial. We need changelogs, and we need them now. But I don’t know how to enforce this at an organizational level.
@regis Yup, it would be something useful and important - but I can also hear the argument that it’s a lot of work to be asking everyone for, especially as a first step. I’m guessing it’s probably not clear to everyone how this will help the project overall - especially to teams within edX who don’t use the stable Open edX releases, and have already a lot of priorities to juggle. Imho that would be something to aim for, but as a further step in a process that starts with smaller steps. It’s also easier to get others to collaborate by starting with contributing things we see as missing ourselves, rather than to condition our contributions on other people’s work. If what we contribute is useful to the project, others will start to depend on it, and it would then be more easy to get other people to contribute to that effort.
There is actually a log being generated of the changes – the PRs being merged. Maybe a way to start building that changelog would be for someone to keep an eye on the PRs, and populate a changelog? The names & descriptions of the PRs being merged would probably be pretty close to a proper changelog format? Maybe some of the PRs might require to ask some questions, but that could be something done on the PRs themselves. Juniper has been cut not so long ago, so there shouldn’t be a lot of backlog yet. And part of the core committer role is to review other people’s PRs, so that could even fall within that scope/status?
Also, I remember that there was a first documentation contribution that had been started some time ago, to document the configuration flags. Finishing it could also be a good next small step in that direction, and an occasion to start discussions around documentation & establish relationships with other developers contributing to Open edX?
I hear what you say @antoviaque: Open edX is open source, and if I am unhappy about something in Open edX, then it’s my responsibility to fix it. However, as gatekeepers and custodians of the Open edX code, edX has some unique responsibilities. One of them is to make sure that developers who contribute to the platform write words about their changes in a human-readable format and put these words somewhere – in a changelog.
To put it bluntly, I refuse to manage another Open edX release if I have zero idea what features and changes are shipped with it. As far as I am concerned, this is just not acceptable anymore.
I don’t know how to make this any more clear 
I have heard this argument multiple times, and this is a common misconception. Just take a look at the list of closed pull requests on edx-platform: Pull requests · openedx/edx-platform · GitHub
- Pull request titles and descriptions are terrible in Open edX.
- There are too many of them for a human to parse (1000-2000 between Ironwood and Juniper) across too many repositories.
- Git commits are not changelog entries
There is no easy way out. Producing a changelog is a fundamental requirement of every open source project. It requires human work by more than one person and cannot be automated. It is not an optional feature. If edX wants to leverage the Open edX community, they need to step up and accept the responsibility.
Yes, this is a work in progress as part of a joint documentation effort between me and EdX. But the goal of this project is not to establish a Changelog – only the documentation of settings and feature toggles across the Open edX codebase. I fail to see how to this could lead to the creation of a changelog.
EDIT: For reference, there exists an OEP on changelogs:
Re-opening this PR and getting it merged would be a first step towards the implementation of changelogs.
I get that it’s an important good practice, but it isn’t really a responsibility edX has - just like any volunteer work, fundamentally we can’t require the volunteer to do more work, only to accept or refuse to use that work. But we wouldn’t refuse to use a new version of Open edX and fork it because it doesn’t have the appropriate documentation, right? It’s not an ideal situation, so it’s worth collaborating to move things in the right direction over time (and it does eventually move in the right direction!) – but I don’t think trying to force more work from edX is going to help with that. I’ve simply never seen that position achieve the desired result within the Open edX community.
That’s too bad. 
Because I think those who will lose out of this are not the ones you are trying to get more work from - it’s going to be the community, who is the one using the Open edX releases – including yourself, as you will have less of a say in the project direction if you let go of leading the release group. It takes time to build trust and relationships, and for our work to be recognized, and reused. But with open source, it only works if we contribute for the good of the project, not as a condition to immediate transformation. With Open edX, patience is key Some decisions evolve over time, the important is to persist - see what happened with the core committers for example; it took seven years to be implemented, and at times it looked hopeless - but not giving up is what allowed it to exist today.
A portion of the PRs titles/descriptions isn’t very hepful currently, true. But at least it’s a starting point, which has the merit of already existing - and arguably a fair number of PRs already have decent descriptions.
Maybe working on improving the quality of the remaining PR descriptions would be an easier project to get support on, than starting a whole new changelog from scratch? And btw, you are now a core committer, so you could review the PRs descriptions which aren’t explicit, and ask questions to help clarifying titles which aren’t good?
Wouldn’t a changelog have a similar issue then? It’s going to be a lot of information to process and compile in any case.
Also, that’s a lot to review in one go, but there was more than a year between those two releases. Done on a daily basis, it’s ~5 PR descriptions to read per day, which seem more attainable?
Yup, I’m just saying that there are other paths to improving documentation and facilitating the upgrades.
True, I actually hadn’t checked the outcome. It isn’t clear whether this was refused though? It seem to have been more delayed?
I think I may have caused some misunderstanding: I’m not trying to strong-arm edX into adopting changelogs. What I am saying is that releasing Open edX is an important responsibility, and I am not in a position to complete this task adequately without changelogs. A changelog is an essential tool which I cannot do without. It’s like trying to code without a keyboard: sure, it’s possible, but it’s really hard and I’m quite simply not up to the task. Maybe someone else is? If yes, I’ll be perfectly happy to help them release Koa. I just don’t want to assume the position of release manager without the proper tooling.
Whatever happens regarding changelogs, I’ll make sure to use my shiny new core committer badge to make new technical propositions, and this is something I’m excited about. There are surely other issues which can be resolved more easily, such as better commit messages, documented operations/settings/feature toggles, easier operations… Open edX is big enough to find other things to work on.
Let’s keep this part of the conversation for the next time we’re having a beer 
Oh God we are going to need a lot more beer.
I really appreciate the energy you both (and others) are putting into this topic. My plan now is to write up a concrete, simple proposal for what we (edX and non-edX) could do. That can at least get more specific discussions going, both inside and outside edX.
1 Like