1# OpenBMC meta layer guidelines 2 3While most of these could be called "rules", in specific scenarios might be 4actively against the intended goals. This is why each guideline has a very large 5"Why" section, to ensure that the intent is being met, and that if exceptions to 6the rules exist, then can be understood and managed by the project. In general, 7if there's a question, and the community agrees, these guidelines can be 8overridden on a case by case basis. 9 10## Meta layers should not patch projects that exist within the openBMC tree 11 12**Why?** 13 14In general, keeping the codebase building in the long term is difficult. Opening 15the possibility that patches exist that repo maintainers aren't aware of makes 16it much more likely that a single machine breaks, or we have behavior 17differences between two repos. 18 19Also, in general, the maintainer is there to ensure that the greater community, 20features, and codebase are prioritized over any one patch, and generally does so 21in code review. If patches are checked into meta layers, generally the 22maintainer is not a reviewer, thereby defeating most of the purpose of the role 23of the maintainer. 24 25**What should I do instead?** 26 27Discuss with the project maintainers and the community about whether or not the 28feature you're building needs to be configurable, or if it can be applied to all 29projects. If it can be applied to all, simply check it into the master branch 30through a gerrit review, and follow the processes outlined for the repository. 31If it needs to be per-project or per-machine configurable, check it in under a 32compile time option, at the suggestion of the maintainer, and add a 33PACKAGECONFIG entry that can be set to enable it. 34 35## Meta layers should not patch Yocto recipes and projects 36 37**Why?** 38 39Yocto itself is an open source project that accepts contributions. The more 40changes that OpenBMC stacks against Yocto recipes, the more unmaintainable it 41becomes, and the longer it takes to rebase to new Yocto versions. In general, 42the Yocto community is as responsive (sometimes much faster) than the OpenBMC 43community in regards to pull requests. 44 45**What should I do instead?** 46 47Submit any changes needed to the Yocto upstream repositories, using their 48process. If the Yocto process has gone several weeks without responses, 49cherry-pick the commit into the OpenBMC tree, with a pointer to the review in 50the commit message, and documentation. The patch commit message should follow 51the Yocto requirements for patch comments, including a statement of the patch 52upstream status. 53[yocto patch requirements](https://wiki.yoctoproject.org/wiki/Best_Known_Methods_%28BKMs%29_for_Package_Updating#Patch_Comments) 54 55## Meta layers should avoid using EXTRA_OEMAKE and EXTRA_OEMESON 56 57**Why?** 58 59There are some OpenBMC projects that are utilized outside of OpenBMC. As such, 60there are configuration items that are not intended to be used in OpenBMC, or 61configuration items that would pose a security risk. Also, as options change and 62are deprecated, the project needs a single place to update the available config 63items and dependencies. 64 65In addition, subprojects might change their build tooling, for example from 66autotools to meson, in pursuit of other goals. Having tool-specific 67configurations makes that change far more difficult to do. 68 69**What should I do instead?** 70 71In the root recipe, add a PACKAGECONFIG entry for the feature in question, then 72use that to enable said feature in your meta layer. 73 74## Meta layers should not have recipes that point to proprietary licensed code 75 76**Why?** 77 78OpenBMC is an open source project, and is intended to be built from source, with 79appropriate distribution licenses such that it can be reused. Pointing to 80commercially licensed repositories actively opposes that goal. 81 82**What should I do instead?** 83 84Find an equivalent open source project that meets the needs, or request that the 85project owner relicenses their project. 86 87## Meta layer recipes should only point to well maintained open source projects 88 89**Why?** 90 91Without this guideline, a loophole is present that allows OpenBMC developers to 92bypass code review by pointing the upstream recipe to a public repository that 93they control, but which OpenBMC has no input on the content of. This splits the 94discussion forums in unproductive ways, and prevents all the other good 95processes within OpenBMC like bug tracking and continuous integration from 96having an effect. 97 98**What should I do instead?** 99 100The advice tends to be on a case by case basis, but if the code is only intended 101for use on OpenBMC, then push a design doc, and push the code to openbmc gerrit 102under the openbmc/openbmc repository where it can be reviewed, along with an 103OWNERS file, signaling your willingness to maintain this project. Then, once the 104community has looked through your design, a repo will be created for code to be 105pushed to. If you're pulling in code from a dead project, inquire to the 106community through the mailing list or discord whether or not the OpenBMC 107community would be willing to adopt support and maintenance of said project. 108 109## Meta layers should not point to OpenBMC specific repositories outside of <https://github.com/openbmc> 110 111**What defines an OpenBMC specific repository?** 112 113Generally an OpenBMC specific repository is something that does any of the 114following: 115 116- Relies on or implements on OpenBMC defined Dbus interfaces. 117- Is not designed with configurability to be used outside of OpenBMC 118- Relies on OpenBMC specific layouts, configuration information to accomplish 119 its primary function. 120 121**Why?** 122 123OpenBMC as a codebase needs to remain buildable in the long term. Companies, 124maintainers, and contributors come and go over the course of the project. 125Keeping all long-term-supported code in the OpenBMC github ensures that the 126project will remain useful. In addition, having significant portions of 127OpenBMC-specific code outside of github limits the ability of the project to do 128refactoring that might be necessary to keep up with the latest best practices, 129Yocto updates, and package revisions, as there isn't always a clear path to 130getting patches accepted when repositories are not within the OpenBMC github 131project 132 133**What should I do instead?** 134 135Discuss the code you'd like to write with the community using the mailing list 136and/or discord. If the design would require a new repository, request one using 137the OpenBMC technical oversight committee process. 138 139## Don't use SRCREV="${AUTOREV}" in a recipe 140 141**Why?** 142 143Repository branches can change at any time. Pointing to an autorev revision 144increases the likelihood that builds break, and makes builds far less 145reproducible. 146 147In addition, having an accounting of exactly what is in your build prevents 148errors when a repo is quietly updated while working, and suddenly changes 149significantly. 150 151**What should I do instead?** 152 153Point SRCREV to a specific commit of the repository, and increase the revision 154either via the autobump script in CI, which can be requested on the mailing 155list, or manually as new revisions exist. 156 157## Meta-layers should not contain compiled code 158 159**Why?** 160 161The project is set up with separate code repositories from the Yocto meta-layer 162repository and there is distinct continuous-integration style testing on each 163repository type. Having code in the meta-layer omits leveraging this CI 164infrastructure and precludes many types of testing and linting we have in place. 165 166Meta-layers are often set up where company-specific developers have merge 167authority. Placing code into these meta-layers allows practices that do not 168conform to broader expectations, without oversight, and lead to company-specific 169implementations and approaches that do not encourage collaboration. 170 171Furthermore, Yocto has historically not had the same level of support for code 172in a meta-layer compared to code in a separate git repository or archive. This 173has been known to cause compile issues in downstream OpenBMC forks. 174 175**What should I do instead?** 176 177Find an existing code repository aligned with your purpose or propose a new one. 178