[Problem] The role of "Maintainer" is unclear

[chennes]

Problem description

In the current version of CONTRIBUTING.md, Maintainer is described as:

A person who merges contributions. Maintainers may or may not be Contributors. Their role is to enforce the process. Maintainers have commit access to the repository.

At the top of that document, the goals are stated as:

1. To provide transparency and fairness in the contribution process.
2. To allow contributions to be included as quickly as possible.
3. To preserve and improve the code quality while encouraging appropriate experimentation and risk-taking.
4. To minimize dependence on individual Contributors by encouraging a large pool of active Contributors.
5. To be inclusive of many viewpoints and to harness a diverse set of skills.
6. To provide an encouraging environment where Contributors learn and improve their skills.
7. To protect the free and open nature of the FreeCAD project.

On one hand, this can lead to the interpretation that a Maintainer's fundamental immediate responsibility is to maintain the codebase itself. In this view, the code is the most important consideration. A Maintainer's job is an in-the-moment consideration of goal 3, "To preserve and improve the code quality", with speed and efficiency of development (goal 2) another central concern.

Another interpretation is that the fundamental work of Maintainers is to facilitate the work of developers, and the building up of a robust developer community. Central to this line of thought is discussion, collaboration, and an eye especially towards goals 1, 4, and 6 -- the idea being that in the long term, a large pool of engaged and active developers will allow us "to preserve and improve the code quality" more effectively, efficiently, and quickly.

We should resolve the primary responsibility of a Maintainer.

Code of Conduct

• I agree to follow this project's Code of Conduct

[sliptonic]

Referring back to the original C4 document that inspired our policy, I see this line:
"The number one goal is size and health of the community--not technical quality, not profits, not performance, not market share."
That implies that they take a longer view of contribution health.

Now that is them, not us but I would still read the goals as well as the role of the maintainer as being consistent with it.

Long term, if we want to go fast, we need a reliable process and a big team. If maintainers have broad discretion to deviate from the process, we'll always debate the correctness of the deviation. Time saved going fast by deviation will be lost to a discussion about the same deviation.

Putting on my Ondsel hat I would say that as a participating organization what I most want to see is predictability.

[sliptonic]

Two observations:
First, reading through the contributing policy I notice that the role, requirement, and process for maintainers is heavily biased toward the solution/PR side of the equation. In fact, the process doesn't even mention maintainers in the context of issues.

Second, the process specifically (step 14) says the maintainers shouldn't make value judgments on the contributions. That doesn't mean the process shouldn't have judgments. It just means those judgments should happen WAY before the code is written.

Considering this together, it makes sense that the maintainers should have a much more explicit role in the issue creation.

Consider this recent example. Issues 8556.
The original problem is really a non-issue. The user is confused by the functionality.
That confusion is the real problem (the UI is confusing for image import)
The discussion evolved toward an improved problem description and some solutions were suggested.
With slightly more discussion, it should reach a consensus on a minimal improvement that solves the problem.

IMHO, part of the maintainer's role should be doing this. They should be offering opinions and value judgment at the issue stage. After all, they are the ones who understand the big picture well enough to guide the discussion toward real improvement.

[chennes]

A quick look at the first page of pull requests shows that just 8 out of 25 mention an Issue. Do we need to start explicitly asking that issues be created? To me that feels heavy-handed, and therefore unwelcoming of new developers. On the other hand, without those issues we are definitely spending more time reviewing PRs than would be ideal, because you first have to establish whether we want the change in question, something that should have been evaluated before the code was written.

[sliptonic]

Requiring it is heavy handed. It starts to feel very artificial to create an issue just to turn around and close it for some minor one-line bug.
This could be an area where the maintainers have more discretion. For example, we might say Maintainers are encouraged to create issues but are allowed to create or accept a PR without one at their discretion for trivial changes.
This doesn't solve the problem since it opens up the can of worms about what is 'trivial'.

At a minimum, I would suggest that any change which affects the user interface, experience, or workflow is not trivial regardless of the size of the PR. If the user sees it, it should be in an issue.

[yorikvanhavre]

We could say something like: Creating an issue first is not mandatory, but understand that if you don't, you might create additional work for maintainers who need to assess if your PR fixes an existing problem, and might delay its handling

[sliptonic]

We could say something like: Creating an issue first is not mandatory, but understand that if you don't, you might create additional work for maintainers who need to assess if your PR fixes an existing problem, and might delay its handling

Expressing a policy like that isn't a good idea. It doesn't give any guidance to the people who most need it - the casual contributors. If we're going to allow exceptions and freedom of action, it should be for people who have experience.

The policy should be as black and white as we can reasonably make it. Perhaps we could say what kinds of issues absolutely require an issue:

1. Anything that affects user experience, user interface, or workflow.
2. Anything that changes a published API
3. Anything that affects document structure
4. Any breaking change to existing models.

We could also require that all first-time contributors MUST create an issue before submitting a PR. this gets them started right and ensures they understand the default process.

[chennes]

MUST create an issue

It's not that they must create an issue, but that their PR must address an issue. And it still feels new-contributor-averse to me: if your one-line PR fixes an obvious problem, then we're asking you to basically triple the amount of work it takes you to fix it. And that's not an uncommon first PR. So I'd be in favor of not having the special case for new contributors. A "thanks for the PR, it looks good, merging now. For tracking and discussion purposes, we would appreciate if in the future if you could create an Issue first" would suffice in many cases.

[sliptonic]

It's not that they must create an issue, but that their PR must address an issue.

that's what I said. Well, it's what I meant anyway. :-P

Hmm. I don't view it as "asking them to triple their work". It's asking them to be familiar with our contribution process. My fear is that if we water it down too far, it has no real value. We're saying, "Here's the 10 things you need to do but, really, just do whatever you want and somebody else will figure it out"

How do we encourage more discipline in the process if we're not going to say anything is binding?

[sliptonic]

In my experience, it isn't the specific steps that people find onerous. It's figuring out which steps apply in a particular case. If we tell them to create (or reference) an issue only if their proposed fix isn't trivial, we're asking them to determine if their issue meets that ambiguous standard. We didn't make the process easier, we made it harder.

Someone should be able to look at the policy and know exactly what they need to do to contribute.

[yorikvanhavre]

Then basically it boils down to "make good PRs".But it's hard to tell newcomers how to do a good PR. it usually comes with a bit of experience.
Maybe we should simply write a kind of good guide, then some "if you want to contribute, read this first"?
Just basically trying to find if we can do without setting hard rules. While hard rules might can make it easier for some, we must also take care that they don't take the fun away

[adrianinsaval]

Can we consider this solved with the stuff in the developers handbook or do we still have stuff to clear up?