1OpenBMC 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 5large "Why" section, to ensure that the intent is being met, and that if 6exceptions to the rules exist, then can be understood and managed by the 7project. In general, if there's a question, and the community agrees, these 8guidelines can be overridden on a case by case basis. 9 101. Meta layers should not patch projects that exist within the openBMC tree. 11 12Why? 13In general, keeping the codebase building in the long term is difficult. 14Opening the possibility that patches exist that repo maintainers aren't aware 15of makes it much more likely that a single machine breaks, or we have behavior 16differences between two repos. 17Also, in general, the maintainer is there to ensure that the greater community, 18features, and codebase are prioritized over any one patch, and generally does so 19in code review. If patches are checked into meta layers, generally the 20maintainer is not a reviewer, thereby defeating most of the purpose of the role 21of the maintainer. 22 23What should I do instead? 24Discuss with the project maintainers and the community about whether or not the 25feature you're building needs to be configurable, or if it can be applied to all 26projects. If it can be applied to all, simply check it into the master branch 27through a gerrit review, and follow the processes outlined for the repository. 28If it needs to be per-project or per-machine configurable, check it in under a 29compile time option, at the suggestion of the maintainer, and add a 30PACKAGECONFIG entry that can be set to enable it. 31 322. Meta layers should not patch Yocto recipes and projects. 33 34Why? 35Yocto itself is an open source project that accepts contributions. The more 36changes that OpenBMC stacks against Yocto recipes, the more unmaintainable it 37becomes, and the longer it takes to rebase to new Yocto versions. In general, 38the Yocto community is as responsive (sometimes much faster) than the OpenBMC 39community in regards to pull requests. 40 41What should I do instead? 42Submit any changes needed to the Yocto upstream repositories, using their 43process. If the Yocto process has gone several weeks without responses, 44cherry-pick the commit into the OpenBMC tree, with a pointer to the review in 45the commit message. 46 473. Meta layers should avoid EXTRA_OEMAKE, EXTRA_OEMESON, arguments in meta 48 layers and bbappends 49 50Why? 51There are some OpenBMC projects that are utilized outside of OpenBMC. As such, 52there are configuration items that are not intended to be used in OpenBMC, or 53configuration items that would pose a security risk. Also, as options change 54and are deprecated, the project needs a single place to update the available 55config items and dependencies. 56In addition, subprojects might change their build tooling, for example from 57autotools to meson, in pursuit of other goals. Having tool-specific 58configurations makes that change far more difficult to do. 59 60What should I do instead? 61In the root recipe, add a PACKAGECONFIG entry for the feature in question, then 62use that to enable said feature in your meta layer. 63 644. Meta layers should not have recipes that point to proprietary licensed code. 65 66Why? 67OpenBMC is an open source project, and is intended to be built from source, with 68appropriate distribution licenses such that it can be reused. Pointing to 69commercially licensed repositories actively opposes that goal. 70 71What should I do instead? 72Find an equivalent open source project that meets the needs, or request that the 73project owner relicenses their project. 74 755. Meta layers recipes should only point to well maintained open source projects 76 77Why? 78Without this guideline, a loophole is present that allows OpenBMC developers to 79bypass code review by pointing the upstream recipe to a public repository that 80they control, but which OpenBMC has no input on the content of. This splits the 81discussion forums in unproductive ways, and prevents all the other good 82processes within OpenBMC like bug tracking and continuous integration from 83having an effect. 84 85What should I do instead? 86The advice tends to be on a case by case basis, but if the code is only intended 87for use on OpenBMC, then push a design doc, and push the code to openbmc gerrit 88under the openbmc/openbmc repository where it can be reviewed, along with an 89OWNERS file, signaling your willingness to maintain this project. Then, once 90the community has looked through your design, a repo will be created for code to 91be pushed to. If you're pulling in code from a dead project, inquire to the 92community through the mailing list or discord whether or not the OpenBMC 93community would be willing to adopt support and maintenance of said project. 94 956. Don't use SRCREV={autorev} in a recipe. 96 97Why? 98Repository branches can change at any time. Pointing to an autorev revision 99increases the likelihood that builds break, and makes builds far less 100reproducible. 101In addition, having an accounting of exactly what is in your build prevents 102errors when a repo is quietly updated while working, and suddenly changes 103significantly. 104 105What should I do instead? 106Point SRCREV to a specific commit of the repository, and increase the revision 107either via the autobump script in CI, which can be requested on the mailing 108list, or manually as new revisions exist. 109