On Fri, 2023-02-17 at 14:54 -0800, Sean Christopherson wrote: > +Branches > +~~~~~~~~ > +The KVM x86 tree is organized into multiple topic branches. The > purpose of > +using finer-grained topic branches is to make it easier to keep tabs > on an area > +of development, and to limit the collateral damage of human errors > and/or buggy > +commits, e.g. dropping the HEAD commit of a topic branch has no > impact on other > +in-flight commits' SHA1 hashes, and having to reject a pull request > due to bugs > +delays only that topic branch. > + > +All topic branches, except for ``next`` and ``fixes`` What's this "fixes" branch for? If fixes for current cycle, will apply to main KVM tree; if fixes for next cycle, why not directly to its topic branch or next branch (kvm- x86 tree)? I see in main KVM tree, its "fixes" branch is very inactive. Too many functional branches will add your maintenance burden. > , are rolled into ``next`` > +via a cthulu merge on an as-needed basis, i.e. when a topic branch > is updated. > +As a result, force pushes to ``next`` are common. > + > +Lifecycle > +~~~~~~~~~ > +Pull requests for the next release cycle are sent to the main KVM > tree, one > +for each KVM x86 topic branch. Will each KVM x86 topic branch has a mapping topic branch in main KVM tree? I mean where is their pull target(s), next branch in main KVM tree? or their counterpart branches in main KVM tree? > If all goes well, the topic branches are rolled > +into the main KVM pull request sent during Linus' merge > window. Pull requests > +for KVM x86 branches are typically made the week before Linus' > opening of the > +merge window, e.g. the week following rc7 for "normal" releases. > + > +The KVM x86 tree doesn't have its own official merge window, but > there's a soft > +close around rc5 for new features, and a soft close around rc6 for > fixes. > + > > +Comments > +~~~~~~~~ > +Write comments using imperative mood and avoid pronouns. Use > comments to > +provide a high level overview of the code, and/or to explain why the > code does > +what it does. Do not reiterate what the code literally does; let > the code > +speak for itself. If the code itself is inscrutable, comments will > not help. Welcome comments that state preconditions for calling this function? e.g. some lock held. > + > +SDM and APM References > +~~~~~~~~~~~~~~~~~~~~~~ > +Much of KVM's code base is directly tied to architectural behavior > defined in > +Intel's Software Development Manual (SDM) and AMD's Architecture > Programmer’s > +Manual (APM). Use of "Intel's SDM" and "AMD's APM", or even just > "SDM" or > +"APM", without additional context is a-ok. > + > +Do not reference specific sections, tables, figures, etc. by number, > especially > +not in comments. Instead, copy-paste the relevant snippet (if > warranted), and > +reference sections/tables/figures by name. The layouts of the SDM > and APM are > +constantly changing, and so the numbers/labels aren't > stable/consistent. Ack
