[Governance] About relations between PR and issues #131

fsologureng commented 2023年01月26日 21:40:54 +01:00

Starting in #124, this sub-discussion is related to defining whether an issue is needed for each pull request.

The proposition was made by @KaKi87 who stated:

a PR is approved only if it implements an already approved issue, i.e. complies with its voted specifications.

and

because they [contributors] only know pieces here and there (until they do it so many times that they become qualified for the maintainer position of course).

The idea is encourage a better vision on the software as a whole.

@crystal, with agreement of @dachary, in an opposite posture argued:

It would obviously be inconvenient for a project maintainer to open both an issue and a pull request for every minor bug they discover and fix on their own, but especially in the case of something like forge software, I think any average user may also want to make such small changes to the codebase. As long as those changes can be quickly reviewed by people who do have more knowledge of the codebase, I think they should be allowed without an existing issue.

---

In short, there are two concerns here:

1. Incentives to contributions with a better understanding of codebase and roadmap.

2. Ease of little contributions without too much bureaucracy.

I think a balance is needed, so please propose solutions.

Personally, I prefer incentives rather than disincentives, so adding effort to those who already have knowledge does not seem to be a good procedure.

(If I am misunderstanding something, please comment)

Starting in #124, this sub-discussion is related to defining whether an issue is needed for each pull request. The proposition [was made](https://codeberg.org/forgejo/meta/issues/124#issuecomment-780331) by @KaKi87 who stated: > *a PR is approved only if it implements an already approved issue, i.e. complies with its voted specifications.* and > *because they [contributors] only know pieces here and there (until they do it so many times that they become qualified for the maintainer position of course).* The idea is encourage a better vision on the software as a whole. @crystal, with agreement of @dachary, in an opposite posture argued: > *It would obviously be inconvenient for a project maintainer to open both an issue and a pull request for every minor bug they discover and fix on their own, but especially in the case of something like forge software, I think any average user may also want to make such small changes to the codebase. As long as those changes can be quickly reviewed by people who do have more knowledge of the codebase, I think they should be allowed without an existing issue.* --- In short, there are two concerns here: 1. Incentives to contributions with a better understanding of codebase and roadmap. 2) Ease of little contributions without too much bureaucracy. I think a balance is needed, so please propose solutions. Personally, I prefer incentives rather than disincentives, so adding effort to those who already have knowledge does not seem to be a good procedure. (If I am misunderstanding something, please comment)

om commented 2023年01月27日 02:47:45 +01:00

Personally, I prefer incentives rather than disincentives, so adding effort to those who already have knowledge does not seem to be a good procedure.

I read all issues related, and i see that this topic comes from a long discussion.

Naturally is always better that the contributer known about the project to make a better contribution, while for the sake of control people who have more knowledge get more responsabilities about all changes.

Is like teachers. They could focus their time to teach, but to do that right, they need to control many other things, that can be modified by any other student.

So, even if i am not a experienced user in pull requests, I undestand the problem.

Is a difficult choice in my interpretation, because any user can see what can become better in some code sample, without knowing anything about the project, while all code change, should pass throught a testing state, to ensure that the commit is healthy to the main project.

You can even try to "split the waters" a little more, saying that for each project, you can have the documentation repository that don't need a specilized control for each issue, and the software repository content that should have a more specilized control.

That would be the "best" solution to this issue i am able to sugest.

> Personally, I prefer incentives rather than disincentives, so adding effort to those who already have knowledge does not seem to be a good procedure. I read all issues related, and i see that this topic comes from a long discussion. Naturally is always better that the contributer known about the project to make a better contribution, while for the sake of control people who have more knowledge get more responsabilities about all changes. *Is like teachers. They could focus their time to teach, but to do that right, they need to control many other things, that can be modified by any other student.* So, even if i am not a experienced user in pull requests, I undestand the problem. Is a difficult choice in my interpretation, because any user can see what can become better in some code sample, without knowing anything about the project, while all code change, should pass throught a testing state, to ensure that the commit is healthy to the main project. You can even try to "split the waters" a little more, saying that for each project, you can have the documentation repository that don't need a specilized control for each issue, and the software repository content that should have a more specilized control. That would be the "best" solution to this issue i am able to sugest.

fsologureng commented 2023年01月27日 15:52:35 +01:00

You can even try to "split the waters" a little more, saying that for each project, you can have the documentation repository that don't need a specilized control for each issue, and the software repository content that should have a more specilized control.

Sorry, I didn't understand which is the concrete suggestion.

> You can even try to "split the waters" a little more, saying that for each project, you can have the documentation repository that don't need a specilized control for each issue, and the software repository content that should have a more specilized control. > Sorry, I didn't understand which is the concrete suggestion.

om commented 2023年01月27日 17:00:22 +01:00

I mean https://codeberg.org/forgejo/meta/src/branch/readme/TEAMS.md

I saw that issue but i didn't add it in my answer..

ignoring or not my "bla bla bla" theory, I mean:

1. You need to create more teams, and evaluate in each team, the time each member can give, maybe defining obligatory tags for each new issue from who create a new one, so teams can filter those in mail to organize their time.

2. Maybe trying to associate more people, while for that, is not a bad idea to create a guide, on how to open issues, so all new issues can follow those rules.

3. Naturally all issues should pass throught a review, even if the owner of that new issue is a experienced developer. Is a good practice in any case but more time consuming is true. For the sake of security, all new code should be reviewed before last commit. In this process you may have a 'experimental'/'testing' branch before commiting all changes in the main code.

4. As i can see, some issues refer other issues, which is the normal process of managing a repository project, so you can organize best practices document.

(i feel it would help me to make better answers and so on)

Sorry if sometimes I have some difficult to be more concrete and specific, but while i may do some mistakes, i learn, like everyone else.

I mean https://codeberg.org/forgejo/meta/src/branch/readme/TEAMS.md I saw that issue but i didn't add it in my answer.. ignoring or not my "bla bla bla" theory, I mean: 1. You need to create more teams, and evaluate in each team, the time each member can give, maybe defining obligatory tags for each new issue from who create a new one, so teams can filter those in mail to organize their time. 2. Maybe trying to associate more people, while for that, is not a bad idea to create a guide, on how to open issues, so all new issues can follow those rules. 3. Naturally all issues should pass throught a review, even if the owner of that new issue is a experienced developer. Is a good practice in any case but more time consuming is true. For the sake of security, all new code should be reviewed before last commit. In this process you may have a 'experimental'/'testing' branch before commiting all changes in the main code. 4. As i can see, some issues refer other issues, which is the normal process of managing a repository project, so you can organize best practices document. (i feel it would help me to make better answers and so on) Sorry if sometimes I have some difficult to be more concrete and specific, but while i may do some mistakes, i learn, like everyone else.

om commented 2023年01月28日 21:51:02 +01:00

Since i wasn't able to explain myself better in the last answer, I will try now.

I refer a lot the issue while this is more focused in pull-request, while in the perspective of a constante code review before commit, all pull-requests come from some issue.

The perspective of having "tags" where not exacly tags but Titles.

The idea is to give a title to the issue, refer groups and content for each repository and define the keywords for new users or teams. So all, new users or developers, use this system to identify what new email they should pay attention.

[Question:Design]: bla bla bla

Then, developer teams may have a email filter with that title definition and get only those notification.. so maybe a redirection for another email or what ever script they can add to their mail system.

Since i wasn't able to explain myself better in the last answer, I will try now. I refer a lot the issue while this is more focused in pull-request, while in the perspective of a constante code review before commit, all pull-requests come from some issue. The perspective of having "tags" where not exacly tags but Titles. The idea is to give a title to the issue, refer groups and content for each repository and define the keywords for new users or teams. So all, new users or developers, use this system to identify what new email they should pay attention. [Question:Design]: bla bla bla Then, developer teams may have a email filter with that title definition and get only those notification.. so maybe a redirection for another email or what ever script they can add to their mail system.

crystal commented 2023年01月31日 13:52:38 +01:00

Personally, I prefer incentives rather than disincentives, so adding effort to those who already have knowledge does not seem to be a good procedure.

I'm not 100% sure what is meant by this. Is there a concern that allowing small contributions from inexperienced contributors will cause a significant additional headache for maintainers and established contributors? I would argue that these types of pull requests are easy to review and don't cause significant churn. On the contrary, some of these contributions may lead to things getting fixed that otherwise would have gone overlooked for too long.

> Personally, I prefer incentives rather than disincentives, so adding effort to those who already have knowledge does not seem to be a good procedure. I'm not 100% sure what is meant by this. Is there a concern that allowing small contributions from inexperienced contributors will cause a significant additional headache for maintainers and established contributors? I would argue that these types of pull requests are easy to review and don't cause significant churn. On the contrary, some of these contributions may lead to things getting fixed that otherwise would have gone overlooked for too long.

fsologureng commented 2023年01月31日 21:58:37 +01:00

Personally, I prefer incentives rather than disincentives, so adding effort to those who already have knowledge does not seem to be a good procedure.

I'm not 100% sure what is meant by this. Is there a concern that allowing small contributions from inexperienced contributors will cause a significant additional headache for maintainers and established contributors? I would argue that these types of pull requests are easy to review and don't cause significant churn. On the contrary, some of these contributions may lead to things getting fixed that otherwise would have gone overlooked for too long.

I will try to rephrase, because the subject of the effort clause wasn't clear: adding additional effort to the proponent requiring the creation of a related issue is counterproductive because is a disincentive to people with acquired knowledge of the code.

But, additionally, you are right, is a disincentive for any kind of contributor.

The important thing to me is, trying to interpret @KaKi87, that reviewers don't loose the direction of the roadmap under a wave of little PR.

By the way, a headache is far gone a normal and healthy intelectual effort and I think is out of this scope :)

> > Personally, I prefer incentives rather than disincentives, so adding effort to those who already have knowledge does not seem to be a good procedure. > > I'm not 100% sure what is meant by this. Is there a concern that allowing small contributions from inexperienced contributors will cause a significant additional headache for maintainers and established contributors? I would argue that these types of pull requests are easy to review and don't cause significant churn. On the contrary, some of these contributions may lead to things getting fixed that otherwise would have gone overlooked for too long. I will try to rephrase, because the subject of the effort clause wasn't clear: adding additional effort to the proponent requiring the creation of a related issue is counterproductive because is a disincentive to people with acquired knowledge of the code. But, additionally, you are right, is a disincentive for any kind of contributor. The important thing to me is, trying to interpret @KaKi87, that reviewers don't loose the direction of the roadmap under a wave of little PR. By the way, a headache is far gone a normal and healthy intelectual effort and I think is out of this scope :)

crystal commented 2023年02月01日 01:17:00 +01:00

That's true, I suppose that was a clumsy metaphor.

That's true, I suppose that was a clumsy metaphor.

gapodo commented 2023年02月01日 15:28:41 +01:00

Since we (at least currently) don't usually do major code rewrites / refractors, I think, that most things can simply be handled on the actual PR (if an issue exists, it should still be linked).

The larger / more invasive a change is, the more it requires actual discussion before implementing it. The measure of large / invasive should not be lines of code (although the effort to review may be larger), but the impact on the software (or docs,...) and the potential technical debt. So...

• fixing a bug -> in most cases not a large point of discussion (unless the bug could be considered a feature by others)
• optimizing code -> likely needs a more thorough review as larger changes tend to be more succeptible to introducing new regressions
• implementing a new feature
  • small things (basically existing functionality presented in a different way) -> review,... but likely not a major discussion
  • bigger features (like e.g. the Forgejo API) -> likely has a long term effect on our codebase
    • should have a discussion (issue) on the architecture, goals, non-goals,...
    • should be split into "work packages" according to the architecture and implementation milestones (i.e. routing endpoint, authentication, basic info,...) to allow for distributed implementation as well as easier maintenance of the PRs (smaller and better encapsulated / defined, makes reviewing easier)
    • then be implemented and reviewed accordingly
    • the discussion may be continued during the whole process, if changes are needed (e.g. when we find a flaw in our architecture,...) the central point of discussion should ease the burden to keep up

Generally I'd like people to open either an issue or open the PR as WIP, to allow others to see, that things are being worked on, thus avoiding multiple people implementing the same thing and only realizing once they open the PR with their "golden commit".

Since we (at least currently) don't usually do major code rewrites / refractors, I think, that most things can simply be handled on the actual PR (if an issue exists, it should still be linked). The larger / more invasive a change is, the more it requires actual discussion before implementing it. The measure of large / invasive should not be lines of code (although the effort to review may be larger), but the impact on the software (or docs,...) and the potential technical debt. So... * fixing a bug -> in most cases not a large point of discussion (unless the bug could be considered a feature by others) * optimizing code -> likely needs a more thorough review as larger changes tend to be more succeptible to introducing new regressions * implementing a new feature * small things (basically existing functionality presented in a different way) -> review,... but likely not a major discussion * bigger features (like e.g. the Forgejo API) -> likely has a long term effect on our codebase * should have a discussion (issue) on the architecture, goals, non-goals,... * should be split into "work packages" according to the architecture and implementation milestones (i.e. routing endpoint, authentication, basic info,...) to allow for distributed implementation as well as easier maintenance of the PRs (smaller and better encapsulated / defined, makes reviewing easier) * then be implemented and reviewed accordingly * the discussion may be continued during the whole process, if changes are needed (e.g. when we find a flaw in our architecture,...) the central point of discussion should ease the burden to keep up Generally I'd like people to open either an issue or open the PR as WIP, to allow others to see, that things are being worked on, thus avoiding multiple people implementing the same thing and only realizing once they open the PR with their "golden commit".

Ghost commented 2023年02月02日 11:27:23 +01:00

Untagging because it is still in the discussion phase and it is not yet clear if this will / should lead to an agreement proposal.

Untagging because it is still in the discussion phase and it is not yet clear if this will / should lead to an agreement proposal.

fsologureng commented 2023年02月03日 00:28:04 +01:00

My impression with respect to several opinions expressed here is that the relevance of the quality of the contributions should be aligned with the roadmap, but at the same time, that guarantee is not well solved by linking PRs to issues.

So I'm going to close this issue on the agreement that linking issues to PRs should not be necessary.

However, I hope someone has a light on how to ensure or incentivise in governance an overview, both in knowledge of the code as its documentation.

My impression with respect to several opinions expressed here is that the relevance of the quality of the contributions should be aligned with the roadmap, but at the same time, that guarantee is not well solved by linking PRs to issues. So I'm going to close this issue on the agreement that **linking issues to PRs should not be necessary**. However, I hope someone has a light on how to ensure or incentivise in governance an overview, both in knowledge of the code as its documentation.