I cc the following content to core@freebsd.org.
Dear Members of the FreeBSD Community and the FreeBSD Core Team,
Proposal to Establish a Dedicated Working Group to Improve the Handling of External Contributions to FreeBSD src, ports, and doc
Please allow me to begin with an ancient story from our country:
Once upon a time, there was a mountain with a dilapidated temple on it. One day, a young monk came to the temple and saw that the water jar was empty. So, he fetched water and filled the jar. Every day, he fetched water, chanted scriptures, and struck the wooden fish, living a peaceful and contented life.
Shortly afterward, a tall monk arrived. Feeling thirsty, he drank half the water in the jar. When the young monk asked him to fetch more water, the tall monk objected to fetching it alone and insisted that they carry it together. So the two monks carried a bucket of water down the mountain. The bucket had to be placed precisely at the center of the carrying pole; otherwise, any imbalance would cause each to push the burden toward the other, with neither willing to do more than his share.
Later, a fat monk came. He also wanted to drink water, but there was no water left in the jar. The young monk and the senior monk asked him to fetch water by himself. The fat monk carried a bucket of water, put it down, and immediately drank greedily. The two buckets of water were completely consumed.
After that, no one fetched water anymore, and the three monks had no water to drink.
This is the story of “One boy is a boy, two boys half a boy, three boys no boy.”
Overview
Given the numerous challenges currently faced by the FreeBSD project in handling external contributions, especially within the three core areas of src, ports, and doc, contributor experience has been seriously affected, and project development has been correspondingly constrained. Therefore, the following proposal is submitted in hopes of drawing attention and promoting relevant improvements:
Focus on Handling GitHub Pull Requests
To avoid fragmented and complicated contribution channels, it is recommended that the proposed working group focus exclusively on Pull Requests (PRs) submitted through GitHub.
Implement time-limit tagging on all submissions via GitHub Actions to enhance time awareness among all involved parties, requiring both external committers and internal FreeBSD committers to respond and handle submissions within the specified deadlines.
Establish a Mandatory Response Mechanism
While understanding that all participants are volunteers, as an external committer who has long experienced delayed handling of submissions (and I am not an isolated case), a clear response and processing timeframe is particularly necessary and reasonable.
This mechanism will help avoid situations where low-complexity submissions, such as simple spelling corrections, are left pending for as long as a year and a half.
Involve More Community Volunteers as Reviewers
It is recommended to involve more community volunteers in review work (a community advisory group may be established simultaneously) to alleviate the pressure on core committers and improve review efficiency.
Core committers would primarily be responsible for final approval and merging, establishing a reasonable division of labor.
Current Project Status Overview
Doc Project: There is a severe shortage of committers, and updates have stagnated. Approximately 30% of the Handbook content is outdated, and most articles are completely obsolete. The current documentation toolchain is complex and outdated, and most committers themselves do not understand it. Furthermore, the documentation mailing list is almost entirely ignored.
Ports Project: Although the number of committers appears sufficient on the surface, external contribution PRs are actually processed slowly, typically taking several months, sometimes even longer.
Src Project: The submission experience requires significant improvement, with overly long processing cycles and a lack of transparent and public handling processes.
Deficiencies of the Current System
Bugzilla only assigns issues to mailing lists without specific responsible individuals, resulting in low handling efficiency.
Phabricator (reviews.freebsd.org) receives very few review responses, with PRs left pending for extended periods and no merging progress.
I have observed that most committers on Phabricator simply say the change is too large and needs further discussion, but in reality, no discussion takes place, causing contributors to simply give up. However, for those familiar with FreeBSD committers, their code is more easily accepted — such as the recent large-scale changes to the Ports category. For those who do not know any committers, their identical contributions are merely told “needs further discussion.” Discuss with whom? The core team or others? In fact, no one. Moreover, based on my personal experience, even after thorough discussion and unanimous agreement, no one steps forward to merge the different patch.
GitHub PRs suffer from similar processing delays.
Lack of Transparency in External Committer Integration
The process by which external contributors become FreeBSD committers is not sufficiently open and transparent. I believe the current problem with FreeBSD is a severe shortage of manpower, but external contributors find it difficult to participate and help share the workload.
I suggest setting up an automated commit bot. There seems to be one currently, but it is seldom used. Such a bot could automatically extract the diff information of the current PR and perform merging.
Additionally, PRs submitted by external contributors are often left pending for long periods, not due to substantive technical discussion but simple procrastination.
Selection of Committer Handling Working Group and Community Advisory Group
The committer handling working group should consist of active FreeBSD committers.
The community advisory group: I believe this should be open to university students, possibly as part of their academic credits, satisfying the need for an active open-source community. The community always needs fresh energy.
I believe the most important thing for external contributors to FreeBSD currently is to enhance the sense of timing among all community volunteers. I fully agree and understand that everyone in the community is unpaid and voluntary; we should not impose KPIs on anyone. However, we all love FreeBSD and are willing to spend time on it, and if we want more people to help us develop and build FreeBSD together, we must implement certain restrictions. I propose a mechanism to suspend inactive members from these two groups. My suggestion is that anyone with no activity for three months should be removed from the group.
At the same time, I think a supervision mechanism should be introduced, holding regular public community video meetings and publishing monthly reports.
We can recognize active contributors in the community monthly reports (I have seen the Ports team sometimes do this in quarterly reports), award special statuses or badges (or simply grant a @freebsd.org email), and invite participation in decision-making meetings to enhance engagement and sense of belonging.
We can also use GitHub projects for progress tracking.
Summary
My view is that if responsibility is simply assigned to a large group, it is very likely that no individual will effectively take action because everyone assumes someone else will do it. We must assign tasks to specific individuals.
Establishing a dedicated external contribution handling working group and a community advisory group, focusing on GitHub PRs, implementing mandatory response deadlines (I consider fifteen days a reasonable limit), and involving more community volunteers in reviews will effectively improve the current external contribution handling efficiency, enhance contributor experience, and promote the sustainable healthy development of the FreeBSD project.
For PRs that cannot be processed promptly, consider introducing a second or third 15-day cycle.
I respectfully urge the Core Team to consider and adopt this proposal.
Thank you!
ykla
Chinese FreeBSD Community
Dear Members of the FreeBSD Community and the FreeBSD Core Team,
Proposal to Establish a Dedicated Working Group to Improve the Handling of External Contributions to FreeBSD src, ports, and doc
Please allow me to begin with an ancient story from our country:
Once upon a time, there was a mountain with a dilapidated temple on it. One day, a young monk came to the temple and saw that the water jar was empty. So, he fetched water and filled the jar. Every day, he fetched water, chanted scriptures, and struck the wooden fish, living a peaceful and contented life.
Shortly afterward, a tall monk arrived. Feeling thirsty, he drank half the water in the jar. When the young monk asked him to fetch more water, the tall monk objected to fetching it alone and insisted that they carry it together. So the two monks carried a bucket of water down the mountain. The bucket had to be placed precisely at the center of the carrying pole; otherwise, any imbalance would cause each to push the burden toward the other, with neither willing to do more than his share.
Later, a fat monk came. He also wanted to drink water, but there was no water left in the jar. The young monk and the senior monk asked him to fetch water by himself. The fat monk carried a bucket of water, put it down, and immediately drank greedily. The two buckets of water were completely consumed.
After that, no one fetched water anymore, and the three monks had no water to drink.
This is the story of “One boy is a boy, two boys half a boy, three boys no boy.”
Overview
Given the numerous challenges currently faced by the FreeBSD project in handling external contributions, especially within the three core areas of src, ports, and doc, contributor experience has been seriously affected, and project development has been correspondingly constrained. Therefore, the following proposal is submitted in hopes of drawing attention and promoting relevant improvements:
Focus on Handling GitHub Pull Requests
To avoid fragmented and complicated contribution channels, it is recommended that the proposed working group focus exclusively on Pull Requests (PRs) submitted through GitHub.
Implement time-limit tagging on all submissions via GitHub Actions to enhance time awareness among all involved parties, requiring both external committers and internal FreeBSD committers to respond and handle submissions within the specified deadlines.
Establish a Mandatory Response Mechanism
While understanding that all participants are volunteers, as an external committer who has long experienced delayed handling of submissions (and I am not an isolated case), a clear response and processing timeframe is particularly necessary and reasonable.
This mechanism will help avoid situations where low-complexity submissions, such as simple spelling corrections, are left pending for as long as a year and a half.
Involve More Community Volunteers as Reviewers
It is recommended to involve more community volunteers in review work (a community advisory group may be established simultaneously) to alleviate the pressure on core committers and improve review efficiency.
Core committers would primarily be responsible for final approval and merging, establishing a reasonable division of labor.
Current Project Status Overview
Doc Project: There is a severe shortage of committers, and updates have stagnated. Approximately 30% of the Handbook content is outdated, and most articles are completely obsolete. The current documentation toolchain is complex and outdated, and most committers themselves do not understand it. Furthermore, the documentation mailing list is almost entirely ignored.
Ports Project: Although the number of committers appears sufficient on the surface, external contribution PRs are actually processed slowly, typically taking several months, sometimes even longer.
Src Project: The submission experience requires significant improvement, with overly long processing cycles and a lack of transparent and public handling processes.
Deficiencies of the Current System
Bugzilla only assigns issues to mailing lists without specific responsible individuals, resulting in low handling efficiency.
Phabricator (reviews.freebsd.org) receives very few review responses, with PRs left pending for extended periods and no merging progress.
I have observed that most committers on Phabricator simply say the change is too large and needs further discussion, but in reality, no discussion takes place, causing contributors to simply give up. However, for those familiar with FreeBSD committers, their code is more easily accepted — such as the recent large-scale changes to the Ports category. For those who do not know any committers, their identical contributions are merely told “needs further discussion.” Discuss with whom? The core team or others? In fact, no one. Moreover, based on my personal experience, even after thorough discussion and unanimous agreement, no one steps forward to merge the different patch.
GitHub PRs suffer from similar processing delays.
Lack of Transparency in External Committer Integration
The process by which external contributors become FreeBSD committers is not sufficiently open and transparent. I believe the current problem with FreeBSD is a severe shortage of manpower, but external contributors find it difficult to participate and help share the workload.
I suggest setting up an automated commit bot. There seems to be one currently, but it is seldom used. Such a bot could automatically extract the diff information of the current PR and perform merging.
Additionally, PRs submitted by external contributors are often left pending for long periods, not due to substantive technical discussion but simple procrastination.
Selection of Committer Handling Working Group and Community Advisory Group
The committer handling working group should consist of active FreeBSD committers.
The community advisory group: I believe this should be open to university students, possibly as part of their academic credits, satisfying the need for an active open-source community. The community always needs fresh energy.
I believe the most important thing for external contributors to FreeBSD currently is to enhance the sense of timing among all community volunteers. I fully agree and understand that everyone in the community is unpaid and voluntary; we should not impose KPIs on anyone. However, we all love FreeBSD and are willing to spend time on it, and if we want more people to help us develop and build FreeBSD together, we must implement certain restrictions. I propose a mechanism to suspend inactive members from these two groups. My suggestion is that anyone with no activity for three months should be removed from the group.
At the same time, I think a supervision mechanism should be introduced, holding regular public community video meetings and publishing monthly reports.
We can recognize active contributors in the community monthly reports (I have seen the Ports team sometimes do this in quarterly reports), award special statuses or badges (or simply grant a @freebsd.org email), and invite participation in decision-making meetings to enhance engagement and sense of belonging.
We can also use GitHub projects for progress tracking.
Summary
My view is that if responsibility is simply assigned to a large group, it is very likely that no individual will effectively take action because everyone assumes someone else will do it. We must assign tasks to specific individuals.
Establishing a dedicated external contribution handling working group and a community advisory group, focusing on GitHub PRs, implementing mandatory response deadlines (I consider fifteen days a reasonable limit), and involving more community volunteers in reviews will effectively improve the current external contribution handling efficiency, enhance contributor experience, and promote the sustainable healthy development of the FreeBSD project.
For PRs that cannot be processed promptly, consider introducing a second or third 15-day cycle.
I respectfully urge the Core Team to consider and adopt this proposal.
Thank you!
ykla
Chinese FreeBSD Community
Last edited:
