Pull request agreement : bug fixes have priority over improvements #337
Labels
No labels
User research - Accessibility
User research - Blocked
User research - Community
User research - Config (instance)
User research - Errors
User research - Filters
User research - Future backlog
User research - Git workflow
User research - Labels
User research - Moderation
User research - Needs input
User research - Notifications/Dashboard
User research - Rendering
User research - Repo creation
User research - Repo units
User research - Security
User research - Settings (in-app)
No milestone
No project
No assignees
9 participants
Notifications
Due date
No due date set.
Reference
forgejo/discussions#337
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
In addition to the existing pull request agreement, what do people think of giving precedence to bug fixes over features? It may help improve the balance between the collective time spent on bug diagnostic and fixing versus time spent on designing new features and implementing them.
It could go like this:
Reproducing a bug and fixing it has higher priority than the design and implementation of a featureReproducing a bug and fixing it is generally expected to have higher priority than the design and implementation of a featureReproducing a bug and fixing it is generally expected to have higher priority than the design and implementation of an improvement (a new feature or the enhancement of an existing behavior)Every contributor has a different way to go about how they contribute and, combined together like pieces of a puzzle, they make Forgejo whole. There recently were a few new contributors who proposed to start contributing to Forgejo and they were naturally drawn to the implementation of new features. It is much more attractive than fixing a bug.
But starting as a new contributor by implementing a new feature is very rarely the best way to help Forgejo because there is a learning curve to understand the codebase, the social dynamics of existing contributors and the pull request agreement (also known as Definition of Done in other contexts). There are, of course, exceptionally talented individuals who are able to learn all this (and more) in total autonomy. But most contributors are normal human being and this learning experience will require time and discussions with other contributors already involved in Forgejo.
Explicitly clarifying that bugs have priority over features shows the path of least resistance to new contributors. While a new feature may linger waiting for attention during a long time, bug fixes are more likely to get a much quicker response time. As social interactions go, working on a bug fix is going to be concluded faster and lead to quicker dialogs with existing contributors. It also helps existing contributors pass along their knowledge in small increments (for instance explaining how to write a test for a bug fix is very often much easier than explaining how to properly tests a new feature).
My first hand experience and daily routine is roughly like this:
I will always spend as much time as requested to answer review requests, even when they are about new features and even if there are more pressing bugs to fix. The reason I prioritize those is because Forgejo needs contributors, more than anything else. If I can help new contributors be involved in Forgejo and increase the chances that they are willing to stay in the long run, this is more important than fixing a single bug. It may be the key to fixing a lot more bugs in the future.
From a personal point of view, I hope the addition of this line to the pull request agreement will help increase the number of new contributors who start with a bug fix rather than a feature.
From the title of this discussion, I was firstly opposed as I thought it would be a hard requirement. But as soft requirement as you proposed it, it sounds fine to me, although it also sounds natural to me, and may not need to be written down. On the other hand, it would be good to attract contributors more towards bug fixing 🤷🏽
Pull request requirement : bug fixes before featuresto Pull request agreement : bug fixes have priority over features@mahlzahn I updated the title to clarify the intent. Is it better?
Also changed the line to be:
It also sounds natural to me. But I've seen new contributors asking which feature they could start working on to contribute to Forgejo a few times. I answered to some of them explaining it would be good to start with fixing a bug. It would help to refer to this discussion and this line of the pull request agreement instead as I suspect it will happen again.
From the perspective of someone who did recently start to contribute, I'm not sure this would have the effect you intend it to have.
It might produce an uptick in quick wins for the really new contributors that went through 'good first issue' labels to get their feet wet. But I feel like it's natural for every contributor to eventually start doing features as well.
Not so much because they are more attractive to work at, but because every contributor will usually also be a user of the software, with their own needs and desires that they would want to drive to implementation.
And some contributors might even start out with the specific intention to implement "that one thing they care about".
So the problem I see is that, regardless of whether a contributor had 2 or 20 small bug fixes merged so far, if they then have a feature PR that they care about get stuck in limbo, they will probably get alienated either way.
If they keep also producing bug fixes and those get merged, they will wonder why their that one PR keeps getting ignored.
If they stop doing other stuff on account of "I want to finish this PR before doing more", they will keep waiting until they forget about it.
So I don't think that shifting towards bug fixes even more than the current situation would have a positive effect on retaining contributors long term.
I also think there would be another negative effect from this:
While in SemVer, a major bump only cares about breaking changes, users might still have the subconscious expectation that a major version should also bring major change.
Even I felt the v11 release somewhat meager in terms of new features.
So if there was an even greater focus on bug fixes, there might be even less to talk about in the blog post.
I think it's good to document this, because I don't think everyone takes that for granted.
There are several open source projects where I would say that features are more important than bug fixes. I get that feeling especially with some "commercialized" projects. Which makes sense. Features are better for marketing and can be sold. Bugs not so much.
In addition I have the feeling that often people have the feeling features receive more recognition in comparision to bug fixes.
@sclu1034 wrote in #337 (comment):
Which is completely fine. It does not forbid contributing features. And features are still relevant and important.
@sclu1034 wrote in #337 (comment):
Mmh, bug fixes are mostly smaller scopes and easier to review. And in addition they have a higher prio, so for me it makes sense, that they are faster reviewed, because most of the time it is easier.
@sclu1034 wrote in #337 (comment):
I think it is more like "let's document the current situation".
@sclu1034 wrote in #337 (comment):
It is possible. I don't remember that ever happening. It is however possible I missed something and if you have seen that, I'd be happy to read through the work of this contributor to better understand how it came to be. My assumption is that it is unlikely to happen because continuously fixing bugs is a very effective way to free some time from existing contributor and make them more likely to spend this time on your own feature request.
In other words I believe (and this goes beyond this discussion) that fixing bugs, just as reviewing other people PRs is part of the routine that help all contributors moving forward. A contributor that does all of that (i) fixing bugs (ii) reviewing pull requests and (iii) implement features will see all move forward more seamlessly than a contributor that specializes in one of those activities.
I considered the "reviewing pull request" topic as well but it is a very difficult one. In other projects (I've not seen that happen in Forgejo) where there is an explicit requirement (or reward) for contributors that review pull requests, it frequently leads to reviews that are more noise than information. In order to be credited for participating in reviews, it a lot easier to comment on tiny details and/or cosmetic correctness and approving rather than making a single request for change that is motivated by an actual problem.
I really second the idea of encouraging bugfixes over features. However, I would like to bring "enhancements" into the consideration. There are many low-hanging fruits in Forgejo that are not a "feature" that can be marketed, but changes to how Forgejo works. Bug fixes from a usability perspective, so to say.
The most prominent example might be to change the way how members are added to an organization. It is not a bug, because the feature works the way it was "designed". It's also not a feature, because nothing new will happen. But it is a valuable improvement, because it's probably the number one confusion issue users have when using Forgejo.
Recently, I got in a serious motivation issue to work on Forgejo. Because my time commitment didn't keep pace with new features, I think we have introduced several usability regressions, or simply areas were UX and accessibility was not evaluated properly. I understand that blocking feature pull requests forever is not a good thing either, but there is a perceived high pressure to unblock those, because people expect them to be finished soon. They might ping you about reviews aggressively, or users ask "why wasn't this merged? This looks good!". Unfortunately, UX and accessibility review is currently not yet a fixed step in the Forgejo development cycle, and fixing things after the fact is much more effort than before something is merged IMHO.
I'm a little frustrated by several contributors, some of them have contributed long-term, who seem to only do "features". Some of them seem to become really angry when their code is not reviewed in time. And if you point out usability issues or suggest changes to the behavior, they refuse to change the way the feature works. It means they intend to get something merged that might be confusing to users.
Personally, what I prefer is to amend an agreement in this direction:
That said, I would interpret this as following:
Pull request agreement : bug fixes have priority over featuresto Pull request agreement : bug fixes have priority over improvements@fnetX wrote in #337 (comment):
Good point. I reworded the proposal and the title to encompass the enhancement of existing behavior.
The divide is between "fixing" and "improving" really.
Hmm, I think I do disagree to that. For me, bugs (behaviour that does not work as it was designed and confuses users) and UX issues (behaviour that works as designed, but still confuses users) mostly fall into the same category: Something does not work as expected.
Sometimes, it is also not really clear whether an existing behaviour that is "weird" is actually a bug, or whether it was really designed to behave that way.
I propose to draw the line between improving existing functionality, either by fixing bugs or enhancing confusing things, and implementing new functionality. However, it is not absolutely necessary to represent this in this agreement. In that spirit, the proposed text could go as follows:
Or, more explicitly:
The mention of user testing is motivated by the fact that this could otherwise get "abused" by declaring everything as an "improvement to existing behavior". Not every button move is really of high priority or even a good idea. Improving an existing feature becomes a good idea when there is clear evidence that users are confused with how a feature works.
I agree with that definition of a bug.
What about a variation of your second line to avoid referring to "user testing" which may not be clear to everyone? The word "demonstrated" is close enough and common language. Moving it to the end keeps the first sentence easy to parse and understand.
What do you think?
Although the "has demonstrated issues during user testing" part doesn't sound that good to me, I still think the variant proposed by Otto - in which improvements are explicitly mentioned together with bug fixes - is more clear.
Maybe reword it like "as well as improving some existing functionality that proved to be confusing for users"?!
What about:
My preference is for "behavior" over "functionality" because it is more general and can encompass many functionalities (which is generally the case when dealing with a UX problem 😁).
As a reviewer, I care to obtain a demonstration, a reasoning based on logic with facts from multiple users to sustain a claim that this is confusing to them. It is not very different than proof but may lead to better results. Show me the demonstration needs to be answered with a reasoning. Show me the proof can be answered with clues/testimonies that are not connected between each other by a reasoning that concludes it is confusing.
@earl-warren wrote in #337 (comment):
I have not yet been part of a project that encouraged or expected new contributors to review pull requests. I've generally only seen non-members start reviewing when they had already been part of the project for a while and aimed to become member, or when they were asked to directly.
If Forgejo wants/needs people inexperienced with the code, and project as a whole, to review PRs, then you'll likely have to communicate this better. I, for one, would not have considered doing that at all at this point.
I guess in part because an approval isn't just a "this code is technically sound", but also a "I agree that the project should move in this direction". I'd assume many people won't be comfortable doing the latter, until they have significant experience with the project.
@earl-warren wrote in #337 (comment):
I guess I kind of fall into that category. Started with going through 'good first issue' (which could be improved, but that's a different discussion), then quickly found a small-ish feature I care about, which is currently stuck on a "will review later". Since then I've not had interest in checking other issue to pick up, and my involvement reduced to meta discussions like this.
But mostly, that scenario was meant as a "worst case" possibility.
@fnetX wrote in #337 (comment):
I believe communication can go a long way in setting the right expectations. E.g. if there were two separate status checks for "approved by code team" & "approved by UX team", and maybe an automated message "sorry, the UX team is currently swamped" and a label 'pending-ux-review', this could got a long way in turning some animosity into patience, or even offering help.
@fnetX wrote in #337 (comment):
Sadly, this does not match with how people consider the term "contributor" in other projects I frequent. They usually come in to fix the one or two issues that bug them personally or to add that one thing to covers their special use case, then leave. And I think this also boils down to expectation setting:
Both GitHub and Forgejo (as a software) define the term as "someone who authored at least one commit in the repository" (via the tag you get in every discussion once your first PR got merged). Therefore, people will often interpret a "we need more contributors" as "we need people that write code". And writing features tends to be their way of "adding something worthwhile to the project".
Wheres what you describe is what I would call a "maintainer". Both because it's a different kind of work, but also because reviewing and decision making tends to be reserved for the trusted members, not the new guy.
I guess my overall concern is that the change you are discussing is mainly going to be read by existing members (I'd expect the pull request agreement to be rather low on the reading list of new contributors, if at all). I.e. you are mainly just affecting the people on the "closing PRs" end.
While the goals you talk about seem to me to be better targeted at the "opening PRs" end, i.e. I think you should be looking at changing text in the Contributor Guide (e.g. fnetX's bullet points).
Or in other words, instead of keeping the incoming PRs the same and trying to change focus on the results, I think you should be steering expectations such that PRs already align with your intentions when they come in.
@sclu1034 wrote in #337 (comment):
Looking at the pull request your proposed they all are features, not bug fixes (including the fist one), which illustrates the point I'm trying to make. When you write that one of your PR is "stuck" and that you "not had interest in checking other issues", I infer that it has not been a pleasant experience and that you would like to find a way to get unstuck.
The message really is as simple as that: if you feel stuck on a feature PR, fix a bug. It will mechanically improve the odds that your feature PR makes progress. It is as simple as that. By freeing the time reviewers spend on fixing bugs you make it possible for them to spend that time on your feature PR.
Does that make sense?
Yes, in the sense that after having taking part in this discussion, I now know how you guys want this to work out.
No, in the sense that me-from-before-the-discussion would not have come to this conclusion naturally, insofar that creating more PRs to review would unblock existing ones for review sounds counterproductive at first.
So I still stand by my comments about expectation management, and think that if documentation is to be changed, it should be spelling this out more clearly, in a location directly visible to (new) contributors, e.g. the Contributor Guide.
The Contributor Guide really needs a series of improvements (I opened a series of issues yesterday as wel), so I agree on that point. Cross-opening an issue.
@earl-warren wrote in #337 (comment):
I was not very attentive at this detail, but "behavior" seems a better choice, indeed (my previous remark was mainly concerning the improvements that are considered bugs; but I think it's just a matter of taste).
Although it's a little bit off-topic, I am also wondering what variant should be used – the American or the British one?
If I'm not mistaken, at some point I asked a similar question (however, I couldn't find that discussionforgejo/website#482 (comment)) and I was told that since most of the involved people are from Europe, British Englishiswas the first option. However, searching through the blog posts and the docs I can find both variants but the US one is more frequent than the UK one (behaviour). And within the company I used to work (from EU with customers mainly from EU) American English was preferred (being considered the business English).I must confess that I resonate with most of the things @sclu1034 mentioned:
In the end I would say that we should all admit that a software having a lot of bugs it's still very annoying even if new (buggy) features are added (at lest I prefer quality over quantity). And we, the contributors, should not forget that maintainers/reviewers time is limited (even responding to comments might take a lot of time) and we should do our best to have patience (a rare feature these days) while our PRs are waiting to be approved and merged.
@floss4good wrote in #337 (comment):
Updated the description accordingly.
Not being a native English speaker, I do not have an opinion on the American vs British matter
These latest comments pretty much express how I feel on this issue and they are well put. I don't have much to add 😁
This is a very personal view of what I consider to be a good experience. I honestly have no idea what general conclusion to draw from that so I'm leaving it here, because I think it is related to this context.
@sclu1034 proposed a new feature three months ago and, at the time, I did not had a chance to interact with them, although they have been around for some time. I had a quick look at the pull request and saw two things: there were not enough testing and the pull request was quite large, so I suggested adding more tests and splitting the pull request. What I did not see at the time was that the pull request was already cleanly organized in smaller commits that made it easier to review: this is a rare quality and I did not think to look.
In the weeks that followed, @sclu1034 fixed bugs, triaged a large amount of bug reports and answered many questions in various Forgejo spaces, almost daily.
Those dialogs were a chance to know @sclu1034 a lot better and when I got back to reviewing the feature request, it significantly changed my perspective. In ways that can be explained such as the confidence that if I made a review comment requiring a change, @sclu1034 would answer within a few days at most (which is helpful for me to not loose context) and that any objections they would have would be clearly articulated. And in ways that cannot be explained and that derive from having a good working relationship with someone and building trust over time.
I've been walking the other side of the road that @earl-warren described in the previous comment. As a contributor, I've seen this discussion happening about prioritizing bug fixes over other improvements. I was a little skeptical when I first read this discussion.
My first change in perspective was to reflect: I've spent decades working in commercial software driven by the need to create features to sell software (or sometimes, to sell software and then create the features that were sold). Every organization I've been a part of, or led, has had "fixing bugs" as effectively the lowest priority work. We fixed the bugs that we were pressured to, and we fixed them with the least resources and least effort possible. It was always frustrating to be in that environment. Why would anyone opt-in to that if they could avoid it?
My second nudge to supporting this proposal was to realize that I have an interest in the development of feature enhancement in a specific area, but I have minuscule levels of experience in the Forgejo codebase. If I was a new hire in a commercial organization, even as an experienced developer, I would surely invest in addressing bugs in order to build my working knowledge of the codebase and the related development processes.
Building some "social capital" as a contributor through bug investments, as described in Earl's last comment, might be the best reason for to support this proposal but the hardest to articulate in simple terms.
Bottom line: this proposal/discussion encouraged me to pick up and address a couple bugs. I wanted to share that so that it's known it had value in nudging behavior. 👍
@mfenniak wrote in #337 (comment):
Indeed. It makes intuitive sense when you think about it. But it is never a given, it is a game of probabilities. There are so many different factors involved when trying to land a new feature and this is only one of them.
Good to know !
Just a data point, I was on the fence about whether to file forgejo/forgejo#9296 as a bug or feature. I probably would have normally decided on 'feature' but this time picked 'bug' since I had just read this part:
forgejo-actions referenced this issue from forgejo/website2025-11-27 18:11:39 +01:00