Date: Sun, 05 Jul 2026 19:13:57 +0000 From: Vladlen Popolitov <vladlen@FreeBSD.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org Subject: git: 189d416d28 - main - books/dev-model: change bibliography links Message-ID: <6a4aacf5.3e056.6f4d74ed@gitrepo.freebsd.org>
index | next in thread | raw e-mail
The branch main has been updated by vladlen: URL: https://cgit.FreeBSD.org/doc/commit/?id=189d416d28a84cc7c8bdf911d75bfeda52e24b42 commit 189d416d28a84cc7c8bdf911d75bfeda52e24b42 Author: Vladlen Popolitov <vladlen@FreeBSD.org> AuthorDate: 2026-07-05 19:13:47 +0000 Commit: Vladlen Popolitov <vladlen@FreeBSD.org> CommitDate: 2026-07-05 19:13:47 +0000 books/dev-model: change bibliography links Approved by: carlavilla Differential Revision: https://reviews.freebsd.org/D58045 --- .../content/en/books/dev-model/_index.adoc | 64 +++++++++++----------- 1 file changed, 31 insertions(+), 33 deletions(-) diff --git a/documentation/content/en/books/dev-model/_index.adoc b/documentation/content/en/books/dev-model/_index.adoc index 04bbac61e1..b33a6e8a70 100644 --- a/documentation/content/en/books/dev-model/_index.adoc +++ b/documentation/content/en/books/dev-model/_index.adoc @@ -79,7 +79,7 @@ Up until now, the FreeBSD project has released a number of described techniques However, a project model summarising how the project is structured is needed because of the increasing amount of project members. footnote:[This goes hand-in-hand with Brooks' law that adding another person to a late project will make it later since it will increase the communication needs . A project model is a tool to reduce the communication needs.] This paper will provide such a project model and is donated to the FreeBSD Documentation project where it can evolve together with the project so that it can at any point in time reflect the way the project works. -It is based on [ crossref:dev-model[thesis, Saers 2003] ]. +It is based on [crossref:dev-model[thesis,"Saers, 2003"]]. I would like to thank the following people for taking the time to explain things that were unclear to me and for proofreading the document. @@ -102,23 +102,23 @@ I would like to thank the following people for taking the time to explain things [[overview]] == Overview A project model is a means to reduce the communications overhead in a project. -As shown by [ crossref:dev-model[brooks, Brooks 1995] ], increasing the number of project participants increases the communication in the project exponentially. +As shown by [crossref:dev-model[brooks,"Brooks, 1995"]], increasing the number of project participants increases the communication in the project exponentially. FreeBSD has during the past few years increased both its mass of active users and committers, and the communication in the project has risen accordingly. This project model will serve to reduce this overhead by providing an up-to-date description of the project. During the Core elections in 2002, Mark Murray stated "I am opposed to a long rule-book, as that satisfies lawyer-tendencies, and is counter to the technocentricity that the project so badly needs." -[ crossref:dev-model[bsd-election2002, FreeBSD 2002B] ]. +[crossref:dev-model[bsd-election2002,"FreeBSD, 2002B"]]. This project model is not meant to be a tool to justify creating impositions for developers, but as a tool to facilitate coordination. It is meant as a description of the project, with an overview of how the different processes are executed. It is an introduction to how the FreeBSD project works. The FreeBSD project model will be described as of July 1st, 2004. -It is based on the Niels Jørgensen's paper [ crossref:dev-model[jorgensen2001, Jørgensen 2001] ], FreeBSD's official documents, discussions on FreeBSD mailing lists and interviews with developers. +It is based on the Niels Jørgensen's paper [crossref:dev-model[jorgensen2001,"Jørgensen, 2001"]], FreeBSD's official documents, discussions on FreeBSD mailing lists and interviews with developers. After providing definitions of terms used, this document will outline the organisational structure (including role descriptions and communication lines), discuss the methodology model and after presenting the tools used for process control, it will present the defined processes. Finally it will outline major sub-projects of the FreeBSD project. -[ crossref:dev-model[freebsd-developer-handbook, FreeBSD 2002A] ] Section 1.2 and 1.3 give the vision and the architectural guidelines for the project. +[crossref:dev-model[freebsd-developer-handbook,"FreeBSD, 2002A"]] Section 1.2 and 1.3 give the vision and the architectural guidelines for the project. The vision is "To produce the best UNIX-like operating system package possible, with due respect to the original software tools ideology as well as usability, performance and stability." The architectural guidelines help determine whether a problem that someone wants to be solved is within the scope of the project @@ -128,8 +128,7 @@ The architectural guidelines help determine whether a problem that someone wants [[ref-activity]] === Activity -An "activity" is an element of work performed during the course of a project -[ crossref:dev-model[ref-pmbok, PMI 2000] ]. +An "activity" is an element of work performed during the course of a project [crossref:dev-model[ref-pmbok,"PMI, 2000"]]. It has an output and leads towards an outcome. Such an output can either be an input to another activity or a part of the process' delivery. @@ -155,7 +154,7 @@ An "outcome" is the final output of the process. This is synonymous with deliverable, that is defined as "any measurable, tangible, verifiable outcome, result or item that must be produced to complete a project or part of a project. Often used more narrowly in reference to an external deliverable, which is a deliverable that is subject to approval by the project sponsor or customer" by -[ crossref:dev-model[ref-pmbok, PMI 2000] ]. +[crossref:dev-model[ref-pmbok,"PMI, 2000"]]. Examples of outcomes are a piece of software, a decision made or a report written. [[ref-freebsd]] @@ -308,7 +307,7 @@ Jørgenssen's model for change integration |=== The "development release" is the FreeBSD-CURRENT ("-CURRENT") branch and the -"production release" is the FreeBSD-STABLE branch ("-STABLE") [ crossref:dev-model[jorgensen2001, Jørgensen 2001] ]. +"production release" is the FreeBSD-STABLE branch ("-STABLE") [crossref:dev-model[jorgensen2001, "Jørgensen, 2001"]]. This is a model for one change, and shows that after coding, developers seek community review and try integrating it with their own systems. After integrating the change into the development release, called FreeBSD-CURRENT, it is tested by many users and developers in the FreeBSD community. @@ -400,7 +399,7 @@ image::branches.png[Refer to table below for a screen-reader friendly version.] |=== The latest -CURRENT version is always referred to as -CURRENT, while the latest -STABLE release is always referred to as -STABLE. -In this figure, -STABLE refers to 4-STABLE while -CURRENT refers to 5.0-CURRENT following 5.0-RELEASE. [ crossref:dev-model[freebsd-releng, FreeBSD 2002E] ] +In this figure, -STABLE refers to 4-STABLE while -CURRENT refers to 5.0-CURRENT following 5.0-RELEASE. [crossref:dev-model[freebsd-releng, "FreeBSD, 2002E"]] A "major release" is always made from the -CURRENT branch. However, the -CURRENT branch does not need to fork at that point in time, but can focus on stabilising. @@ -460,14 +459,14 @@ These hat descriptions are not such a formalisation, rather a summary of the rol A Contributor contributes to the FreeBSD project either as a developer, as an author, by sending problem reports, or in other ways contributing to the -progress of the project. A contributor has no special privileges in the FreeBSD project. [ crossref:dev-model[freebsd-contributors, FreeBSD 2002F] ] +progress of the project. A contributor has no special privileges in the FreeBSD project. [crossref:dev-model[freebsd-contributors, "FreeBSD, 2002F"]] [[role-committer]] ==== Committer A person who has the required privileges to add their code or documentation to the repository. A committer has made a commit within the past 12 months. -[ crossref:dev-model[freebsd-developer-handbook, FreeBSD 2000A] ] An active committer is a committer who has made an average of one commit per month during that time. +[crossref:dev-model[freebsd-developer-handbook, "FreeBSD, 2000A"]] An active committer is a committer who has made an average of one commit per month during that time. It is worth noting that there are no technical barriers to prevent someone, once having gained commit privileges to the main- or a sub-project, to make commits in parts of that project's source the committer did not specifically get permission to modify. However, when wanting to make modifications to parts a committer has not been involved in before, they should read the logs to see what has happened in this area before, and also read the MAINTAINERS file to see if the maintainer of this part has any special requests on how changes in the code should be made. @@ -706,11 +705,10 @@ After this, the new committer is all set to make their first commit. By tradition, this is by adding their name to the committers list. Recall that a committer is considered to be someone who has committed code during the past 12 months. -However, it is not until after 18 months of inactivity have passed that commit privileges are eligible to be revoked. -[ crossref:dev-model[freebsd-expiration-policy, FreeBSD 2002H] ] +However, it is not until after 18 months of inactivity have passed that commit privileges are eligible to be revoked. [crossref:dev-model[freebsd-expiration-policy, "FreeBSD, 2002H"]] There are, however, no automatic procedures for doing this. For reactions concerning commit privileges not triggered by time, see -crossref:dev-model[process-reactions,section 1.5.8]. +crossref:dev-model[process-reactions,section 6.7]. .Process summary: removing a committer image::proc-rm-committer.png[Refer to paragraph below for a screen-reader friendly version.] @@ -729,9 +727,9 @@ Roles in this process: . crossref:dev-model[role-maintainer, Maintainership] . crossref:dev-model[role-mentor, Mentor] -[ crossref:dev-model[freebsd-bylaws, FreeBSD 2000A] ] -[ crossref:dev-model[freebsd-expiration-policy, FreeBSD 2002H] ] -[ crossref:dev-model[freebsd-new-account, FreeBSD 2002I] ] +[crossref:dev-model[freebsd-bylaws, "FreeBSD, 2000A"]], +[crossref:dev-model[freebsd-expiration-policy, "FreeBSD, 2002H"]], +[crossref:dev-model[freebsd-new-account, "FreeBSD, 2002I"]]. [[committing]] === Committing code @@ -782,8 +780,8 @@ Hats included in this process are: . crossref:dev-model[role-vendor, Vendor] . crossref:dev-model[role-reviewer, Reviewers] -[ crossref:dev-model[freebsd-committer, FreeBSD 2001] ] -[ crossref:dev-model[jorgensen2001, Jørgensen 2001] ] +[crossref:dev-model[freebsd-committer, "FreeBSD, 2001"]], +[crossref:dev-model[jorgensen2001, "Jørgensen, 2001"]]. [[process-core-election]] === Core election @@ -824,16 +822,16 @@ Hats in core elections are: * crossref:dev-model[role-committer, Committer] * crossref:dev-model[role-election-manager, Election Manager] -[ crossref:dev-model[freebsd-bylaws, FreeBSD 2000A] ] -[ crossref:dev-model[bsd-election2002, FreeBSD 2002B] ] -[ crossref:dev-model[freebsd-election, FreeBSD 2002G] ] +[crossref:dev-model[freebsd-bylaws, "FreeBSD, 2000A"]], +[crossref:dev-model[bsd-election2002, "FreeBSD, 2002B"]], +[crossref:dev-model[freebsd-election, "FreeBSD, 2002G"]]. [[new-features]] === Development of new features Within the project there are sub-projects that are working on new features. These projects are generally done by one person -[ crossref:dev-model[jorgensen2001, Jørgensen 2001] ]. +[crossref:dev-model[jorgensen2001, "Jørgensen, 2001"]]. Every project is free to organise development as it sees fit. However, when the project is merged to the -CURRENT branch it must follow the project guidelines. When the code has been well tested in the -CURRENT branch and deemed stable enough and relevant to the -STABLE branch, it is merged to the -STABLE branch. @@ -870,7 +868,7 @@ footnote:[sendmail and named are examples of code that has been merged from othe The maintainer's job is to make sure the code is in sync with the project the code comes from if it is contributed code, and apply patches submitted by the community or write fixes to issues that are discovered. The main bulk of work that is put into the FreeBSD project is maintenance. -[ crossref:dev-model[jorgensen2001, Jørgensen 2001] ] has made a figure showing the life cycle of changes. +[crossref:dev-model[jorgensen2001, "Jørgensen, 2001"]] has made a figure showing the life cycle of changes. Jørgenssen's model for change integration @@ -952,13 +950,13 @@ The roles included in this process are: . crossref:dev-model[role-maintainer, Maintainership] . crossref:dev-model[role-bugbuster, Bugbuster] -[ crossref:dev-model[freebsd-handle-pr, FreeBSD 2002C] ]. -[ crossref:dev-model[freebsd-send-pr, FreeBSD 2002D] ]. +[crossref:dev-model[freebsd-handle-pr, "FreeBSD, 2002C"]], +[crossref:dev-model[freebsd-send-pr, "FreeBSD, 2002D"]]. [[process-reactions]] === Reacting to misbehavior -[ crossref:dev-model[freebsd-committer, FreeBSD 2001] ] has a number of rules that committers should follow. +[crossref:dev-model[freebsd-committer, "FreeBSD, 2001"]] has a number of rules that committers should follow. However, it happens that these rules are broken. The following rules exist in order to be able to react to misbehavior. They specify what actions will result in how long a suspension of the committer's commit privileges. @@ -968,7 +966,7 @@ They specify what actions will result in how long a suspension of the committer' * Commit wars - 5 days to all participating parties * Impolite or inappropriate behavior - 5 days -[ crossref:dev-model[ref-freebsd-trenches, Lehey 2002] ] +[crossref:dev-model[ref-freebsd-trenches, "Lehey, 2002"]]. For the suspensions to be efficient, any single core member can implement a suspension before discussing it on the "core" mailing list. Repeat offenders can, with a 2/3 vote by core, receive harsher penalties, including permanent removal of commit privileges. @@ -1044,7 +1042,7 @@ For slips of time not to become too long with regards to security and stability // Keep the spaces around the external square bracket to avoid a warning in the // PDF converter -[ crossref:dev-model[freebsd-releng, FreeBSD, 2002E] ] +[crossref:dev-model[freebsd-releng, "FreeBSD, 2002E"]]. [[tools]] == Tools @@ -1074,7 +1072,7 @@ The FreeBSD Project uses it to run 16 general lists, 60 technical lists, 4 limit It is also used for many mailing lists set up and used by other people and projects in the FreeBSD community. General lists are lists for the general public, technical lists are mainly for the development of specific areas of interest, and closed lists are for internal communication not intended for the general public. The majority of all the communication in the project goes through these 85 lists -[ crossref:dev-model[ref-bsd-handbook, FreeBSD 2003A], Appendix C]. +[crossref:dev-model[ref-bsd-handbook, "FreeBSD, 2003A"], Appendix C]. [[tool-pgp]] === Pretty Good Privacy @@ -1142,7 +1140,7 @@ Only documentation errors are corrected in the security branches. Like the ports sub-project, the Documentation project can appoint documentation committers without FreeBSD Core's approval. -[ crossref:dev-model[freebsd-doceng-charter, FreeBSD 2003B] ]. +[crossref:dev-model[freebsd-doceng-charter, "FreeBSD, 2003B"]]. The Documentation project has extref:{fdp-primer}[a primer]. This is used both to introduce new project members to the standard tools and syntaxes and to act as a reference when working on the project. @@ -1160,7 +1158,7 @@ This is used both to introduce new project members to the standard tools and syn [Saers, 2003] Niklas Saers. Copyright © 2003. A project model for the FreeBSD Project. Candidatus Scientiarum thesis. http://niklas.saers.com/thesis. [[jorgensen2001]] -[Jørgensen, 2001] Niels Jørgensen. Copyright © 2001. Putting it All in the Trunk. Incremental Software Development in the FreeBSD Open Source Project. http://www.dat.ruc.dk/~nielsj/research/papers/freebsd.pdf. +[Jørgensen, 2001] Niels Jørgensen. Copyright © 2001. Putting it All in the Trunk. Incremental Software Development in the FreeBSD Open Source Project. http://webhotel4.ruc.dk/~nielsj/research/publications/freebsd.pdf. [[ref-pmbok]] [PMI, 2000] Project Management Institute. Copyright © 1996, 2000 Project Management Institute. 1-880410-23-0. Project Management Institute. Newtown Square Pennsylvania USA . PMBOK Guide. A Guide to the Project Management Body of Knowledge, 2000 Edition.home | help
Want to link to this message? Use this
URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?6a4aacf5.3e056.6f4d74ed>