├── README.md ├── index.md ├── LICENSE ├── template.md ├── fcp-0100.md ├── fcp-20190401-ci_policy.md ├── fcp-0101.md └── fcp-0000.md /README.md: -------------------------------------------------------------------------------- 1 | # FreeBSD Community Proposals 2 | 3 | This is the repository containing the FreeBSD Community Proposals, see the [index](./index.md). 4 | 5 | If you're looking for how to write a FreeBSD Community Proposal you should 6 | start with [FCP 0](./fcp-0000.md) and the 7 | [template](./template.md). 8 | 9 | A good place to ask questions is the fcp-editors@freebsd.org list. 10 | -------------------------------------------------------------------------------- /index.md: -------------------------------------------------------------------------------- 1 | # This is the index of all FCPs 2 | 3 | FCP | State | Owners | Title 4 | --------------------------|-----------|-----------------------|------ 5 | [FCP 0](./fcp-0000.md) | accepted | allanjude, gnn, benno | FreeBSD Community Proposal Process and Authoring Guide 6 | [FCP 100](./fcp-0100.md) | draft | imp | Creating armv7 MACHINE_ARCH 7 | [FCP 101](./fcp-0101.md) | accepted | brooks | Deprecation and removal of 10/100 Ethernet drivers 8 | [FCP 20190401-ci_policy](./fcp-20190401-ci_policy.md) | feedback | kp, lwhsu | CI policy 9 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Redistribution and use in source and binary forms, with or without 2 | modification, are permitted provided that the following conditions are met: 3 | 4 | 1. Redistributions of source code must retain the above copyright notice, this 5 | list of conditions and the following disclaimer. 6 | 7 | 2. Redistributions in binary form must reproduce the above copyright notice, 8 | this list of conditions and the following disclaimer in the documentation 9 | and/or other materials provided with the distribution. 10 | 11 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 12 | ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 13 | WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 14 | DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE 15 | FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 16 | DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 17 | SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 18 | CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 19 | OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 20 | OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 21 | -------------------------------------------------------------------------------- /template.md: -------------------------------------------------------------------------------- 1 | --- 2 | authors: Contributor Name , 3 | Collaborator Name 4 | state: draft 5 | --- 6 | 7 | # FCP -1: FreeBSD Community Proposal Template 8 | 9 | This is a good place for an abstract. Abstracts are a brief summary of the 10 | content of the proposal. For example this is a template and as such acts as 11 | a guide, though not a strict one, as to how your FreeBSD Community Proposal 12 | should be formatted. 13 | 14 | ## Problem Statement 15 | 16 | A good way to start your FreeBSD Community Proposal is to describe in a 17 | sufficient level of clarity the problem you're trying to solve. In this case 18 | we lack a simple example for contributors to follow when writing their 19 | proposals. 20 | 21 | ## Problem Discussion 22 | 23 | This is where we can go into the problem in more detail. For instance in this 24 | case we can talk about how the lack of an example FCP means that people may 25 | not write up proposals as they don't know exactly how to structure the 26 | document. The lack of an example could also lead to a bunch of issues that 27 | would need to be brought up by people on the fcp-editors list. While the 28 | fcp-editors list is a resource that should absolutely be used for advice and 29 | discussion on your FCP before you put it up for discussion an example would 30 | cover the most obvious issues and mean that the fcp-editors could focus on 31 | other issues. Lastly having an example would just be nice. 32 | 33 | ## Proposed Solution 34 | 35 | We will write an example FCP that provides a decent template for contributors 36 | to follow. This example FCP will be provided as a template and will follow all 37 | the basic formatting and structure conventions we want to see from an FCP. 38 | 39 | ## Solution Discussion 40 | 41 | Clear-eyed people may notice that the structure of this example is different 42 | from that of [FCP 0](./FCP-0000.md). This is not a bug. In most cases 43 | this structure will work but if it doesn't allow you to properly express and 44 | discuss your proposal you should feel free to change that. 45 | 46 | Formatting is a different matter. This example is in 47 | [Markdown](https://guides.github.com/features/mastering-markdown/#syntax), has 48 | hard line breaks at 80 columns and has a metadata block at the top that 49 | lists all the authors of this proposal and its current state. You should 50 | always do these things in your proposal. 51 | 52 | Once you've finished writing your proposal you should follow the instructions 53 | in [FCP 0](./FCP-0000.md) to move forward. 54 | 55 | Good luck! 56 | 57 | ## Final Disposition 58 | 59 | This section is for detailing the reasoning behind the final status of the FCP. 60 | If you withdraw your FCP you can outline your reasons here. If core accepts 61 | or rejects the FCP they can add their reasoning here. It should not be present 62 | in FCPs prior to the `accepted`, `rejected` or `withdrawn` states. 63 | -------------------------------------------------------------------------------- /fcp-0100.md: -------------------------------------------------------------------------------- 1 | --- 2 | author: M Warner Losh 3 | state: draft 4 | changed: 2017-06-09T16:20+0000 5 | --- 6 | 7 | 13 | 14 | # FCP 100: Adding armv7 MACHINE_ARCH 15 | 16 | A new MACHINE_ARCH for the armv7 machines is needed. While one can 17 | support armv6 and armv7 in one architecture, it creates a lot of 18 | unnecessary friction. 19 | 20 | While it initially felt like similar to the difference between i486 21 | and i586, the number of changes required to make this happen are 22 | larger, especially in ports. Linux has agressively adopted armv7 as 23 | its processor name. In addition, being able to optimize differently 24 | between armv6 and armv7 will help enable or disable newer programs 25 | like lld. 26 | 27 | ## Changes to the system 28 | 29 | ### Build Changes 30 | 31 | * Change the build infrastructure to accept armv7 as a valid target. 32 | * Change the build infrastructure to generate code optimized for armv7 target. 33 | * Change the build infrastructure to have the same speical cases for armv7 that we have for armv6. 34 | 35 | ### Kernel Changes 36 | * Have all the kernels, except RPI-B, use armv7 as the target arch, so uname -p returns the right name. 37 | * Rename RPI-B to GENERICv6 since it is the only board that's supported with an armv6 SoC. 38 | * armv7 and armv6 binaries look pretty close to the same, so we'll need some way to not run armv7 binaries on an armv6 kernels. 39 | 40 | ### Ports Changes 41 | * All ports that have tried to shoe-horn in the current infrasture need to be examined and likely modified. 42 | * Ports exp run will need to be run for both armv6 and the new armv7 43 | * Package infrastructure will need to grow armv7 support 44 | 45 | ### Handbook Changes 46 | * Need to change places where we document the lists of valid architectures. 47 | 48 | ### Man page Changes 49 | * build(7) and arch(7) need to be updated to reflect armv7. 50 | * src.conf(5) needs to be regenerated with armv7 in the list 51 | * cloudabi(4) needs to add armv7 to the list of supported architectures 52 | 53 | ### RE Changes 54 | * We'll need to migrate the armv6 stuff to armv7. 55 | * Add new arch. Normally this is a hassle, but it's movement in this case, not additions. 56 | 57 | ## Impacts 58 | 59 | ### Interfaces 60 | 61 | Currently, many things are based on the machine processor being armv6. Those would need to be audited and change. There will be customer visible downstream changes needed. 62 | 63 | ### Upgrade 64 | 65 | We'll need some way to support upgrades on either side of the integration into the tree. 66 | 67 | ### Packages 68 | 69 | We'll need some way to upgrade armv6 packages to armv7. 70 | 71 | ## Paths Not Taken 72 | 73 | Linux uses armv7l or armv7b for this. NetBSD uses earmv7hf and 74 | earmv7hfbe. Regardless of what we do, we can't leverage either of 75 | these names to make ports easier. And since neither matches FreeBSD's 76 | other architectures, or historic practice on the arm, we've decided to 77 | go forward with 'armv7' and will use 'armv7be' if necessary. 78 | -------------------------------------------------------------------------------- /fcp-20190401-ci_policy.md: -------------------------------------------------------------------------------- 1 | --- 2 | authors: Kristof Provost , 3 | Li-Wen Hsu 4 | state: feedback 5 | --- 6 | 7 | # FCP 20190401-ci_policy: CI policy 8 | 9 | This document aims to present a set of policies to ensure that the FreeBSD base system 10 | consistently builds and functions correctly. 11 | 12 | ## Problem Statement 13 | 14 | FreeBSD has a continuous integration system (currently managed with Jenkins) at 15 | https://ci.freebsd.org to validate that the base system compiles for 16 | most supported architectures and configurations. The same tool also runs 17 | automated tests for the base system. 18 | 19 | Sometimes developers commit changes which break compilation on one or more 20 | platforms or cause test failures. Finally, a panic or a similar problem during 21 | a test run may prevent us from obtaining any test results at all. 22 | 23 | One of the main functions of the CI system is letting committers know if there 24 | is a build failure or test regression as early as possible. FreeBSD's CI 25 | system is configured to send failure or instability notifications to the committer 26 | and the dev-ci@freebsd.org mailing list. Ideally the original committer responds to 27 | these notifications by committing a fix or revert themselves. If these 28 | reports are not addressed in a timely manner a number of negative effects 29 | compound: 30 | 31 | - Other issues may be hidden by this failure 32 | - Development on affected platforms may be blocked 33 | - Downstream users may struggle to find a usable version 34 | 35 | While developers are usually very responsive to reports of build failures, they 36 | may not always know how to resolve a specific issue promptly, or may not have the time to immediately 37 | address it. 38 | 39 | Other developers do not always feel empowered to revert such commits. 40 | 41 | ## Proposed Solution 42 | 43 | We propose a policy explicitly empowering developers to revert commits which 44 | cause compilation problems, test failures, or panics during tests. 45 | 46 | We describe the recommended steps to take, notifications to send, 47 | and recommended timeout periods. 48 | 49 | ### Notification 50 | 51 | Everyone (committers and non-committers alike) is 52 | encouraged to investigate failures in non-experimental jobs [1]. 53 | The investigator should prepare a report identifying the commit which triggered 54 | the failure as well as details about the failure (for example, compile errors or 55 | output from failing tests). The investigator should 56 | send this report to all of the following: 57 | 58 | - The author of the triggering commit 59 | - Other people, if any, who've touched the relevant code after the triggering 60 | commit 61 | - The dev-ci@freebsd.org list (to avoid duplicate notifications) 62 | 63 | ### Waiting period 64 | 65 | Once the notification has been sent, the author of the problematic commit should 66 | be given a reasonable amount of time to respond. 67 | This time will vary depending on the severity of the problem and how many 68 | platforms it affects: 69 | 70 | - If a commit broke compilation on all platforms, it can be reverted after 71 | 15 minutes 72 | - If a commit broke compilation on a tier 1 platform, it can be reverted after 73 | 4 hours 74 | - If a commit broke compilation on tier 2 or 3 platforms, it can be reverted 75 | after 12 hours 76 | - If a commit triggers a panic during the automated test run (and thus blocks 77 | all tests), it can be reverted after 24 hours 78 | - If a commit causes a test regression (of one of the automated tests), it can 79 | be reverted after 48 hours 80 | 81 | Note that these are minimal guidelines. If the author of the problem has 82 | responded with a request for more time this will be respected within reason. 83 | 84 | ### Revert 85 | 86 | If a commit must be reverted, the commit message should 87 | explicitly mention the revision it is reverting and explain why. 88 | 89 | For example: 90 | 91 | Revert rNNNNNN: 92 | 93 | This does not build in i386: 94 | 95 | 96 | [1] Non-experimental job means a job which sends build status notifications to 97 | the committer or the dev-ci@freebsd.org list. 98 | -------------------------------------------------------------------------------- /fcp-0101.md: -------------------------------------------------------------------------------- 1 | --- 2 | authors: Brooks Davis 3 | state: accepted 4 | --- 5 | 6 | # FCP 101: Deprecation and removal of 10/100 Ethernet drivers 7 | 8 | Deprecate most 10 and 10/100Mbps Ethernet drivers and remove them before 9 | FreeBSD 13. 10 | 11 | ## Problem Statement 12 | 13 | Each network driver creates drag for the project as we attempt to 14 | improve the network stack or provide new features such as expanded 15 | 32-bit compatibility. For example, the author has edited every single 16 | NIC driver more than once in the past year to update management (`ioctl`) 17 | interfaces. We could improve this situation by converting drivers to 18 | iflib, but each additional driver takes work. 19 | 20 | 10 and 100 megabit Ethernet drivers are largely irrelevant today 21 | and we have a significant number of them in the tree. The ones that 22 | are no longer used and/or are not known to be working need to be 23 | removed due to the significant ongoing 'tax' on new development. 24 | 25 | For at least a decade, most systems (including small embedded 26 | systems) have shipped with gigabit Ethernet devices and virtual 27 | machines commonly emulate popular gigabit devices. We wish to 28 | retain support for popular physical and virtual devices while 29 | removing support for uncommon ones. With a few exceptions these 30 | drivers are unlikely to be used by our user base by the time FreeBSD 31 | 12 is obsolete. 32 | 33 | ## Proposed Solution 34 | 35 | We propose to deprecate devices which are not sufficiently popular. This 36 | will entail: 37 | - (October 2018) Send this list to freebsd-net and freebsd-stable. 38 | - (Before FreeBSD 12.0-RELEASE - October 2018) Update the manpages and 39 | attach routines for each device to be removed and merge those changes 40 | to FreeBSD 12. 41 | - (One month after FreeBSD 12.0-RELEASE - January 2019) Remind 42 | freebsd-net and freebsd-stable users of pending deletion. 43 | - (Three months after FreeBSD 12.0-RELEASE - March/April 2019) Delete 44 | deprecated devices. 45 | 46 | Through out this process, solicit feedback on additions to the exception 47 | list and this document will be updated as required. Drivers can have 48 | their deprecation notices removed at any time if it is justified. For a 49 | device to be placed on the exception list the device must meet one of 50 | the following criteria: 51 | 52 | - Popular in applications where it is likely to be deployed beyond the 53 | support lifetime of FreeBSD 12 (late 2023). 54 | - 5 reports of uses in the wild on machines running or expected to 55 | promptly upgrade to FreeBSD 12 will be deemed to satisfy the "popular" 56 | requirement. 57 | - Required to make a well supported embedded or emulation platform usable. 58 | - Ported to use iflib (reducing future maintenance cost.) 59 | 60 | ### Exceptions to removal 61 | 62 | Device | Reason 63 | -------|------------------------------------------------- 64 | ae | Popular in Asus 701, etc. 65 | bfe | Cleared the popularity bar during feedback. 66 | dc | Popular device for CardBus card. 67 | dme | Built in interface on Creator CI20 and Ingenic JZ47XX. 68 | fxp | Popular device long recommended by the project. 69 | hme | Built in interface on many supported sparc64 platforms. 70 | le | Emulated by QEMU, alternatives don't yet work for mips64. 71 | rl | Popular in the P-III era and reported to ship in embedded systems. 72 | sis | Soekris Engineering net45xx, net48xx, lan1621, and lan1641. 73 | smc | ARM Foundation Model simulator. 74 | ste | Deployed 2-/4-port cards are hard to replace. 75 | vr | Soekris Engineering net5501, some Asus motherboards. 76 | vte | Still shipping in embedded systems, GbE capable (not in tree). 77 | xl | Popular device for CardBus card. 78 | 79 | Note: USB devices have been excluded from consideration in this round. 80 | 81 | ### Device to be removed 82 | 83 | bm, cs, de, ed, ep, ex, fe, pcn, sf, sn, tl, tx, txp, vx, wb, xe 84 | 85 | ## Summary of discussions and supporting data 86 | 87 | The discussing this FCP (primarily on FreeBSD-arch) resulted in 106 88 | emails. There was one request to restrict deprecation to 10Mbps 89 | devices and a few calls for a much shorter list. Based on the 90 | discussions we moved a number of devices to the STAY list. Some 91 | interest was expressing in doing iflib converstions, but documentation 92 | on the process is currently lacking. Most interest centered around rl 93 | which will remain the tree. 94 | 95 | I've tallied the results below breaking them down between mentions of 96 | systems people intend to run 12-RELEASE on and other mentions of actual 97 | systems (I've ignored entirely hypothetical mentions along the lines of 98 | "XXX used to be really popular".) 99 | 100 | | Driver | Will run 12 | Other | Notes | 101 | |--------|-------------|-------|-------| 102 | | ae | 2 | 2 | | 103 | | at | 0 | 1 | | 104 | | bfe | 5 | 0 | Popular, moved to STAY list | 105 | | de | 0 | 0 | One mention without context | 106 | | ed | 1 | 2 | | 107 | | ep | 0 | 1 | | 108 | | pcn | 1 | 0 | | 109 | | rl | 6+ | 1 | Popular, moved to STAY list | 110 | | sf | 0 | 1 | | 111 | | vx | 0 | 1 | | 112 | 113 | ### NYCBUG dmesg survey (as of 2018-10-18) 114 | 115 | Warner Losh solicited posts to https://dmesgd.nycbug.org/ and produced 116 | the following data on drivers considered in this FCP. The data is thin 117 | and certainly contains bias due to the manual and voluntary submission 118 | process, but it is the data we have. 119 | 120 | | Driver | 8.x | 9.x | 10.x | 11.x | 12.x | 121 | | --- | --- | --- | --- | --- | --- | 122 | | ae | 0 | 0 | 0 | 0 | 0 | 123 | | bfe | 1 | 0 | 0 | 0 | 1 | 124 | | bm | 0 | 0 | 0 | 0 | 0 | 125 | | cs | 0 | 0 | 0 | 0 | 0 | 126 | | de | 0 | 0 | 0 | 1 | 0 | 127 | | dme | 0 | 0 | 0 | 0 | 0 | 128 | | ed | 0 | 0 | 0 | 0 | 0 | 129 | | ep | 0 | 0 | 0 | 0 | 0 | 130 | | ex | 0 | 0 | 0 | 0 | 0 | 131 | | fe | 0 | 0 | 0 | 0 | 0 | 132 | | pcn | 0 | 0 | 0 | 0 | 0 | 133 | | sf | 0 | 0 | 0 | 0 | 0 | 134 | | sn | 0 | 0 | 0 | 0 | 0 | 135 | | tl | 0 | 0 | 0 | 0 | 0 | 136 | | tx | 0 | 0 | 0 | 0 | 0 | 137 | | txp | 0 | 0 | 0 | 0 | 0 | 138 | | vx | 0 | 0 | 0 | 0 | 0 | 139 | | wb | 0 | 0 | 0 | 0 | 0 | 140 | | xe | 0 | 0 | 0 | 0 | 0 | 141 | | rl | 2 | 1 | 1 | 5 | 1 | 142 | | fxp | 3 | 2 | 1 | 6 | 2 | 143 | | xl | 1 | 0 | 0 | 3 | 0 | 144 | | samples | 57 | 55 | 178 | 502 | 183 | 145 | 146 | ## Note to users of deprecated devices 147 | 148 | If you are here because you see a deprecation notice for hardware you 149 | are using, please report your use to the author of this FCP for tabulation. 150 | Also, please consider submitting your dmesg to 151 | https://dmesgd.nycbug.org/. 152 | -------------------------------------------------------------------------------- /fcp-0000.md: -------------------------------------------------------------------------------- 1 | --- 2 | author: Allan Jude , 3 | George V. Neville-Neil , 4 | Benno Rice 5 | state: accepted 6 | changed: 2017-06-09T16:20+0000 7 | --- 8 | 9 | 17 | 18 | # FCP 0: FreeBSD Community Proposal Process and Authoring Guide 19 | 20 | The FreeBSD project has adopted a model of discussion and collaboration 21 | for major changes called FreeBSD Community Proposals, or FCPs. This 22 | model is based on [Requests for Comments](https://tools.ietf.org/html/rfc3) 23 | (RFCs) that originated with the IETF. 24 | 25 | FCPs use the 26 | [Markdown](https://guides.github.com/features/mastering-markdown/#syntax) 27 | format for text formatting. 28 | 29 | FCPs use the IETF interpretations of the keywords "MUST", "MUST NOT", 30 | "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 31 | and "OPTIONAL" as defined in [RFC 2119](https://tools.ietf.org/html/rfc2119). 32 | 33 | The rest of this FCP documents when, why, and how to write an FCP. 34 | 35 | ## When should an FCP be written? 36 | 37 | The purpose of the FCP process is to document the design decisions behind 38 | proposed changes and gather feedback from the many different types of users 39 | that make up the FreeBSD community about how a change will impact them. 40 | 41 | There are no strict rules as to when an FCP should be written, but here 42 | are some examples of when creating an FCP is a good idea: 43 | 44 | * A change lacks consensus or is significantly contended. 45 | * Creating, changing, or removing a feature is likely to cause user 46 | confusion, a violation of the Principle of Least Astonishment (POLA). 47 | * A change breaks the behavior of existing commands or libraries. 48 | * A substantive change to the behavior or function of the ports or packaging 49 | system. 50 | * A change significantly impacts how people interact with the FreeBSD 51 | community. 52 | * A change that is proposed or committed which results in significant 53 | objections SHOULD use the FCP process to come to a resolution. 54 | * Proposing a change to FreeBSD community tools or processes. 55 | 56 | ## The Structure of an FCP 57 | 58 | Every FCP MUST have a title that is a simple synopsis of the document. FCPs 59 | are dated to allow the title to change. An FCP MUST have the 60 | following attributes: 61 | 62 | * **Title**: A simple synopsis of the document. The title may change as the 63 | FCP evolves. 64 | * **Date**: [YYYYMMDD] An easy numerical reference to the FCP. MUST be the date 65 | the proposal was first introduced. 66 | * **Metadata**: Information to track the authors and state of the FCP. 67 | 68 | An FCP SHOULD address these questions: 69 | 70 | ##### What is the problem to be solved? 71 | 72 | Clearly describe the problem with enough detail for someone 73 | unfamiliar with the issue to understand the proposed 74 | solution. Give a description and discussion of the problem first. Follow this 75 | with a separate description and discussion of the proposed solution. Keep the 76 | problem and solution descriptions and discussions separate for clarity. 77 | 78 | Examples of problems are: 79 | 80 | * The lack of a feature. 81 | * A needed improvement to an existing feature. 82 | * An ambiguity in the functionality of the system. 83 | * An issue with a community process. 84 | 85 | ##### How will users interact with these new or changed features? 86 | 87 | How will this change affect users? How will it affect existing scripts or other 88 | integrations with the system? How will it impact programs that link against 89 | base system libraries? 90 | 91 | All users of the system MUST be considered. FreeBSD is used by many individuals 92 | as well as directly and indirectly by many larger organizations and these MUST 93 | be taken into account. 94 | 95 | ##### Will this change any public or private interfaces? 96 | 97 | If a public interface such as a command line program or its arguments, a 98 | library, or a syscall is to be changed, list it here along with a brief 99 | description of the intended change. 100 | 101 | Changes to private interfaces, those consumed by other internal parts of 102 | FreeBSD, MUST also be listed with a similarly brief description of the intended 103 | change. 104 | 105 | ##### What is the upgrade impact? 106 | 107 | What are the implications to current users of FreeBSD if they upgrade their 108 | systems to a newer version that includes this change? Can the change be merged 109 | to the stable branch? Any such changes MUST be added to the UPDATING file in 110 | the main FreeBSD repository. 111 | 112 | ##### What is the security impact? 113 | 114 | What potentially untrusted user input, whether data or code, will be handled 115 | by the system as part of the change? Which components will interact with that 116 | input? How will that input be validated and managed securely? What new or 117 | changed privileges will your feature require? How can the new code be 118 | sandboxed? How might an attacker use the proposed facilities to escalate their 119 | privileges? 120 | 121 | ## FCP States 122 | 123 | An FCP can be in one of the following states: 124 | 125 | 1. draft 126 | 1. feedback 127 | 1. vote 128 | 1. accepted 129 | 1. rejected 130 | 1. withdrawn 131 | 132 | An FCP is first created in the `draft` state. Before publicizing 133 | the FCP to the mailing lists, the author is encouraged to contact 134 | fcp-editors@freebsd.org for editorial review. When the draft is ready, it moves 135 | to the `feedback` state and is published to the fcp@freebsd.org mailing list 136 | and CCed to other appropriate forums like related technical lists. 137 | 138 | The `feedback` state is where all discussion of the FCP takes place. Various 139 | contributors will provide feedback on the changes proposed in the FCP and their 140 | impact on the FreeBSD project. FCPs MAY have code attached to them, whether 141 | example code or a reference to a set of patches that can be reviewed. 142 | 143 | When the discussion of a change has come to a suitable and acceptable close it 144 | SHOULD be updated to the `vote` state. 145 | 146 | At this time the FreeBSD Core Team will vote on the subject of the FCP. The 147 | result of vote moves the FCP into the `accepted` or `rejected` state. 148 | 149 | FCPs in the `accepted` state can be updated and corrected. 150 | See the "Changes after acceptance" section for more information. 151 | 152 | The authors may withdraw an FCP at any time. If an FCP is not 153 | viable or if an FCP is to be ignored, it can be moved into the `withdrawn` 154 | state. 155 | 156 | ## Mechanics of an FCP 157 | 158 | To create a new FCP, an author MUST take the following steps. 159 | 160 | ### Write the first draft 161 | 162 | A [template](./template.md) is provided in the 163 | [FCP repository](https://github.com/freebsd/fcp). FCPs MUST have a text width 164 | of 80 columns. Extra material such as code samples, graphs, and other materials may 165 | be provided and MUST be named starting with the FCP filename like this: 166 | 167 | `fcp-YYYYMMDD-shortname_code-sample-1.c` 168 | 169 | #### FCP Metadata 170 | 171 | Every FCP document MUST start with a brief amount of metadata in the 172 | [python-markdown2](https://github.com/trentm/python-markdown2/wiki/metadata) 173 | metadata format as follows: 174 | 175 | ``` 176 | --- 177 | authors: Committer Name , 178 | Collaborator Name 179 | state: draft 180 | changed: 2017-06-09T15:17+0000 181 | --- 182 | ``` 183 | 184 | Only `authors` and `state` values are tracked. There MAY be any number of 185 | `authors`. `Author` entries MUST contain both name and e-mail address for 186 | proper attribution. A `changed` entry SHOULD be present and indicate the date 187 | the FCP was last modified. If present this attribute MUST be in 188 | [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations) 189 | format and in the UTC time zone. An appropriate 190 | timestamp can be generated with this command: 191 | 192 | `$ date -u +%Y-%m-%dT%H:%M%z` 193 | 194 | ### Publish the FCP 195 | 196 | The FCP MUST be published under a filename of the form: 197 | 198 | `fcp-YYYYMMDD-XXXX.md` 199 | 200 | The XXXX MUST be replaced with a short name to idenify the subject of the FCP. 201 | 202 | The FCP MUST then be added to the 203 | [FCP repository](https://github.com/freebsd/fcp) either using the functionality 204 | provided on the Github website or by creating a branch and raising a pull 205 | request. Adding the FCP to the repository SHOULD be done in the same pull request 206 | as adding it to the `index.md`. If the author lacks 207 | a GitHub account or needs assistance they SHOULD contact fcp-editors@freebsd.org. 208 | 209 | The FCP must be added to the repository in the `draft` state. 210 | 211 | ### Gather input on the FCP 212 | 213 | After the FCP has been published, the author should seek input from the 214 | fcp-editors@freebsd.org list and any other contributors or forums that seem 215 | appropriate. If this feedback results in edits to the FCP these edits MUST 216 | be reflected in the FCP repository as soon as practical. The `changed` metadata 217 | attribute, if present, MUST be kept up to date. 218 | 219 | When the author feels an FCP is complete, it 220 | can move on to the `feedback` state described below. 221 | 222 | ### Start the feedback process 223 | 224 | Feedback begins when the FCP document itself and the FCP index 225 | document in the repository are updated to indicate that the FCP is in the 226 | `feedback` state. The FCP MUST then be announced on the fcp@freebsd.org list 227 | and any other forums, like topic-specific mailing lists, that are appropriate 228 | to the content of the FCP. 229 | 230 | The subject of the announcement MUST include the FCP filename and title. The 231 | body of the announcement MUST include a link to the FCP along with a summary 232 | which can be any abstract or summary from the document itself. 233 | 234 | As the feedback process continues, any edits to the FCP MUST be reflected in 235 | the repository copy as soon as is practical. The `changed` metadata attribute, 236 | if present, MUST be kept up to date. 237 | 238 | ### Submit to core vote 239 | 240 | After the feedback process has concluded, the author MUST request a vote on the 241 | FCP by updating the FCP itself and the index to indicate it is in the 242 | `vote` state. The FCP author MUST also notify core@freebsd.org. The email 243 | to core MUST have the FCP filename and title in the subject line and a summary 244 | of the FCP along with a link to the repository copy of the FCP in the body. 245 | The author SHOULD provide pointers to relevant discussion on the FCP in the 246 | various forums where it has been discussed. 247 | 248 | Core MAY request more information if it is needed to 249 | inform their vote. Core MAY also notify the author that additional 250 | time is needed to deliberate. If core has not specifically requested additional time, 251 | core MUST complete its deliberation and voting process within two weeks. 252 | 253 | The core vote will result in the FCP being moved to either the `accepted` or 254 | `rejected` states. This state MUST be reflected in the FCP document and in 255 | the index. Core MAY add a section to the FCP detailing the reasoning behind 256 | their decision. 257 | 258 | ### Withdrawal 259 | 260 | At any point prior to the resolution of the core vote, the 261 | author MAY withdraw their FCP. If an FCP is withdrawn it MUST be indicated in 262 | the FCP itself and the FCP index by changing the FCP state to `withdrawn`. 263 | The author MAY add a section to the FCP detailing the reasoning behind the 264 | withdrawal. 265 | 266 | ### Changes after acceptance 267 | 268 | FCPs may need revision after they have been moved into the `accepted` 269 | state. In such cases, the author SHOULD update the FCP to reflect the final conclusions. If 270 | the changes are major, the FCP SHOULD be withdrawn and restarted. 271 | --------------------------------------------------------------------------------