1*d078e0d2SEd TanousOpenBMC meta layer guidelines 2*d078e0d2SEd Tanous 3*d078e0d2SEd TanousWhile most of these could be called "rules", in specific scenarios might be 4*d078e0d2SEd Tanousactively against the intended goals. This is why each guideline has a very 5*d078e0d2SEd Tanouslarge "Why" section, to ensure that the intent is being met, and that if 6*d078e0d2SEd Tanousexceptions to the rules exist, then can be understood and managed by the 7*d078e0d2SEd Tanousproject. In general, if there's a question, and the community agrees, these 8*d078e0d2SEd Tanousguidelines can be overridden on a case by case basis. 9*d078e0d2SEd Tanous 10*d078e0d2SEd Tanous1. Meta layers should not patch projects that exist within the openBMC tree. 11*d078e0d2SEd Tanous 12*d078e0d2SEd TanousWhy? 13*d078e0d2SEd TanousIn general, keeping the codebase building in the long term is difficult. 14*d078e0d2SEd TanousOpening the possibility that patches exist that repo maintainers aren't aware 15*d078e0d2SEd Tanousof makes it much more likely that a single machine breaks, or we have behavior 16*d078e0d2SEd Tanousdifferences between two repos. 17*d078e0d2SEd TanousAlso, in general, the maintainer is there to ensure that the greater community, 18*d078e0d2SEd Tanousfeatures, and codebase are prioritized over any one patch, and generally does so 19*d078e0d2SEd Tanousin code review. If patches are checked into meta layers, generally the 20*d078e0d2SEd Tanousmaintainer is not a reviewer, thereby defeating most of the purpose of the role 21*d078e0d2SEd Tanousof the maintainer. 22*d078e0d2SEd Tanous 23*d078e0d2SEd TanousWhat should I do instead? 24*d078e0d2SEd TanousDiscuss with the project maintainers and the community about whether or not the 25*d078e0d2SEd Tanousfeature you're building needs to be configurable, or if it can be applied to all 26*d078e0d2SEd Tanousprojects. If it can be applied to all, simply check it into the master branch 27*d078e0d2SEd Tanousthrough a gerrit review, and follow the processes outlined for the repository. 28*d078e0d2SEd TanousIf it needs to be per-project or per-machine configurable, check it in under a 29*d078e0d2SEd Tanouscompile time option, at the suggestion of the maintainer, and add a 30*d078e0d2SEd TanousPACKAGECONFIG entry that can be set to enable it. 31*d078e0d2SEd Tanous 32*d078e0d2SEd Tanous2. Meta layers should not patch Yocto recipes and projects. 33*d078e0d2SEd Tanous 34*d078e0d2SEd TanousWhy? 35*d078e0d2SEd TanousYocto itself is an open source project that accepts contributions. The more 36*d078e0d2SEd Tanouschanges that OpenBMC stacks against Yocto recipes, the more unmaintainable it 37*d078e0d2SEd Tanousbecomes, and the longer it takes to rebase to new Yocto versions. In general, 38*d078e0d2SEd Tanousthe Yocto community is as responsive (sometimes much faster) than the OpenBMC 39*d078e0d2SEd Tanouscommunity in regards to pull requests. 40*d078e0d2SEd Tanous 41*d078e0d2SEd TanousWhat should I do instead? 42*d078e0d2SEd TanousSubmit any changes needed to the Yocto upstream repositories, using their 43*d078e0d2SEd Tanousprocess. If the Yocto process has gone several weeks without responses, 44*d078e0d2SEd Tanouscherry-pick the commit into the OpenBMC tree, with a pointer to the review in 45*d078e0d2SEd Tanousthe commit message. 46*d078e0d2SEd Tanous 47*d078e0d2SEd Tanous3. Meta layers should avoid EXTRA_OEMAKE, EXTRA_OEMESON, arguments in meta 48*d078e0d2SEd Tanous layers and bbappends 49*d078e0d2SEd Tanous 50*d078e0d2SEd TanousWhy? 51*d078e0d2SEd TanousThere are some OpenBMC projects that are utilized outside of OpenBMC. As such, 52*d078e0d2SEd Tanousthere are configuration items that are not intended to be used in OpenBMC, or 53*d078e0d2SEd Tanousconfiguration items that would pose a security risk. Also, as options change 54*d078e0d2SEd Tanousand are deprecated, the project needs a single place to update the available 55*d078e0d2SEd Tanousconfig items and dependencies. 56*d078e0d2SEd TanousIn addition, subprojects might change their build tooling, for example from 57*d078e0d2SEd Tanousautotools to meson, in pursuit of other goals. Having tool-specific 58*d078e0d2SEd Tanousconfigurations makes that change far more difficult to do. 59*d078e0d2SEd Tanous 60*d078e0d2SEd TanousWhat should I do instead? 61*d078e0d2SEd TanousIn the root recipe, add a PACKAGECONFIG entry for the feature in question, then 62*d078e0d2SEd Tanoususe that to enable said feature in your meta layer. 63*d078e0d2SEd Tanous 64*d078e0d2SEd Tanous4. Meta layers should not have recipes that point to proprietary licensed code. 65*d078e0d2SEd Tanous 66*d078e0d2SEd TanousWhy? 67*d078e0d2SEd TanousOpenBMC is an open source project, and is intended to be built from source, with 68*d078e0d2SEd Tanousappropriate distribution licenses such that it can be reused. Pointing to 69*d078e0d2SEd Tanouscommercially licensed repositories actively opposes that goal. 70*d078e0d2SEd Tanous 71*d078e0d2SEd TanousWhat should I do instead? 72*d078e0d2SEd TanousFind an equivalent open source project that meets the needs, or request that the 73*d078e0d2SEd Tanousproject owner relicenses their project. 74*d078e0d2SEd Tanous 75*d078e0d2SEd Tanous5. Meta layers recipes should only point to well maintained open source projects 76*d078e0d2SEd Tanous 77*d078e0d2SEd TanousWhy? 78*d078e0d2SEd TanousWithout this guideline, a loophole is present that allows OpenBMC developers to 79*d078e0d2SEd Tanousbypass code review by pointing the upstream recipe to a public repository that 80*d078e0d2SEd Tanousthey control, but which OpenBMC has no input on the content of. This splits the 81*d078e0d2SEd Tanousdiscussion forums in unproductive ways, and prevents all the other good 82*d078e0d2SEd Tanousprocesses within OpenBMC like bug tracking and continuous integration from 83*d078e0d2SEd Tanoushaving an effect. 84*d078e0d2SEd Tanous 85*d078e0d2SEd TanousWhat should I do instead? 86*d078e0d2SEd TanousThe advice tends to be on a case by case basis, but if the code is only intended 87*d078e0d2SEd Tanousfor use on OpenBMC, then push a design doc, and push the code to openbmc gerrit 88*d078e0d2SEd Tanousunder the openbmc/openbmc repository where it can be reviewed, along with an 89*d078e0d2SEd TanousOWNERS file, signaling your willingness to maintain this project. Then, once 90*d078e0d2SEd Tanousthe community has looked through your design, a repo will be created for code to 91*d078e0d2SEd Tanousbe pushed to. If you're pulling in code from a dead project, inquire to the 92*d078e0d2SEd Tanouscommunity through the mailing list or discord whether or not the OpenBMC 93*d078e0d2SEd Tanouscommunity would be willing to adopt support and maintenance of said project. 94*d078e0d2SEd Tanous 95*d078e0d2SEd Tanous6. Don't use SRCREV={autorev} in a recipe. 96*d078e0d2SEd Tanous 97*d078e0d2SEd TanousWhy? 98*d078e0d2SEd TanousRepository branches can change at any time. Pointing to an autorev revision 99*d078e0d2SEd Tanousincreases the likelihood that builds break, and makes builds far less 100*d078e0d2SEd Tanousreproducible. 101*d078e0d2SEd TanousIn addition, having an accounting of exactly what is in your build prevents 102*d078e0d2SEd Tanouserrors when a repo is quietly updated while working, and suddenly changes 103*d078e0d2SEd Tanoussignificantly. 104*d078e0d2SEd Tanous 105*d078e0d2SEd TanousWhat should I do instead? 106*d078e0d2SEd TanousPoint SRCREV to a specific commit of the repository, and increase the revision 107*d078e0d2SEd Tanouseither via the autobump script in CI, which can be requested on the mailing 108*d078e0d2SEd Tanouslist, or manually as new revisions exist. 109