요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
Patchwork status와 review timeline
maintainer-netdev.rst:108-265Patchwork의 New, Under Review, Changes Requested, Accepted, Rejected 상태는 queue 처리 상황을 나타낸다. Author가 임의로 status를 바꾸기보다 review reply와 새 revision으로 상태 변화를 만든다.
자동 check가 끝나고 reviewer가 볼 시간을 준다. Changes Requested 뒤에는 comment를 모두 반영한 full series를 다시 보내고, 일부 patch만 resend하면 dependency와 numbering이 모호해질 수 있어 maintainer가 허용한 경우에만 한다.
Patch가 잘못된 tree에 적용됐다면 즉시 thread에서 알리고 revert·drop 여부를 maintainer와 조정한다. Silent replacement나 history rewrite로 이미 소비된 commit을 바꾸지 않는다.
Stable과 security fix
maintainer-netdev.rst:266-286Stable candidate는 netdev mainline fix로 먼저 merge하고 Fixes와 stable Cc를 사용한다. Exploitable issue는 public netdev posting 전에 security@kernel.org 절차로 coordination한다.
Userspace component와 selftest co-posting
maintainer-netdev.rst:287-321Ethtool, iproute2와 libbpf 같은 userspace change가 필요한 kernel API는 관련 project patch도 같은 discussion에서 볼 수 있게 link하거나 co-post한다. Kernel selftest는 code change와 함께 보내 API 사용 예제와 regression coverage를 제공한다.
Series 구성과 local declaration
maintainer-netdev.rst:322-434Target tree를 subject·cover에 표시하고 logical change별로 patch를 나눈다. Netdev 주변 code가 사용하는 reverse Christmas tree declaration ordering은 local convention을 따른다. Generic kernel style, subsystem style과 tool output이 충돌하면 netdev handbook의 precedence를 확인한다.
Device-managed resource와 cleanup.h guard는 lifetime, error-path 가독성과 subsystem precedent를 보고 선택한다. Cleanup-only patch를 functional change와 섞지 않고 review 뒤 resend에는 version changelog와 retained tag를 정확히 관리한다.
Expected testing, patchwork check와 netdevsim
maintainer-netdev.rst:435-526Build만이 아니라 affected protocol, namespace, offload, MTU와 error path를 실행한다. kselftest, packetdrill, traffic test와 relevant driver test 결과를 적고 patchwork의 build·checkpatch·selftest failure를 확인한다.
실제 hardware 없이 control path를 검증할 수 있으면 netdevsim을 사용하되 real NIC의 DMA, interrupt와 firmware behavior를 대체한다고 주장하지 않는다. Maintained driver는 regression report와 API conversion에 대응할 담당자가 있어야 한다.
Reviewer가 확인할 범위
maintainer-netdev.rst:527-553Reviewer는 packet lifetime, skb ownership, locking·RCU, NAPI context, feature negotiation, UAPI compatibility와 hardware offload fallback을 함께 본다. 단순 style 지적만 하지 않고 observable behavior와 test gap을 구체적으로 남긴다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
.. SPDX-License-Identifier: GPL-2.0
.. _netdev-FAQ:
=============================
Networking subsystem (netdev)
=============================
tl;dr
-----
- designate your patch to a tree - ``[PATCH net]`` or ``[PATCH net-next]``
- for fixes the ``Fixes:`` tag is required, regardless of the tree
- don't post large series (> 15 patches), break them up
- don't repost your patches within one 24h period
- reverse xmas tree
netdev
------
netdev is a mailing list for all network-related Linux stuff. This
includes anything found under net/ (i.e. core code like IPv6) and
drivers/net (i.e. hardware specific drivers) in the Linux source tree.
Note that some subsystems (e.g. wireless drivers) which have a high
volume of traffic have their own specific mailing lists and trees.
Like many other Linux mailing lists, the netdev list is hosted at
kernel.org with archives available at https://lore.kernel.org/netdev/.
Aside from subsystems like those mentioned above, all network-related
Linux development (i.e. RFC, review, comments, etc.) takes place on
netdev.
Development cycle
-----------------
Here is a bit of background information on
the cadence of Linux development. Each new release starts off with a
two week "merge window" where the main maintainers feed their new stuff
to Linus for merging into the mainline tree. After the two weeks, the
merge window is closed, and it is called/tagged ``-rc1``. No new
features get mainlined after this -- only fixes to the rc1 content are
expected. After roughly a week of collecting fixes to the rc1 content,
rc2 is released. This repeats on a roughly weekly basis until rc7
(typically; sometimes rc6 if things are quiet, or rc8 if things are in a
state of churn), and a week after the last vX.Y-rcN was done, the
official vX.Y is released.
To find out where we are now in the cycle - load the mainline (Linus)
page here:
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
and note the top of the "tags" section. If it is rc1, it is early in
the dev cycle. If it was tagged rc7 a week ago, then a release is
probably imminent. If the most recent tag is a final release tag
(without an ``-rcN`` suffix) - we are most likely in a merge window
and ``net-next`` is closed.
git trees and patch flow
------------------------
There are two networking trees (git repositories) in play. Both are
driven by David Miller, the main network maintainer. There is the
``net`` tree, and the ``net-next`` tree. As you can probably guess from
the names, the ``net`` tree is for fixes to existing code already in the
mainline tree from Linus, and ``net-next`` is where the new code goes
for the future release. You can find the trees here:
- https://git.kernel.org/pub/scm/linux/kernel/git/netdev/net.git
- https://git.kernel.org/pub/scm/linux/kernel/git/netdev/net-next.git
Relating that to kernel development: At the beginning of the 2-week
merge window, the ``net-next`` tree will be closed - no new changes/features.
The accumulated new content of the past ~10 weeks will be passed onto
mainline/Linus via a pull request for vX.Y -- at the same time, the
``net`` tree will start accumulating fixes for this pulled content
relating to vX.Y
An announcement indicating when ``net-next`` has been closed is usually
sent to netdev, but knowing the above, you can predict that in advance.
.. warning::
Do not send new ``net-next`` content to netdev during the
period during which ``net-next`` tree is closed.
RFC patches sent for review only are obviously welcome at any time
(use ``--subject-prefix='RFC net-next'`` with ``git format-patch``).
Shortly after the two weeks have passed (and vX.Y-rc1 is released), the
tree for ``net-next`` reopens to collect content for the next (vX.Y+1)
release.
If you aren't subscribed to netdev and/or are simply unsure if
``net-next`` has re-opened yet, simply check the ``net-next`` git
repository link above for any new networking-related commits. You may
also check the following website for the current status:
https://netdev.bots.linux.dev/net-next.html
The ``net`` tree continues to collect fixes for the vX.Y content, and is
fed back to Linus at regular (~weekly) intervals. Meaning that the
focus for ``net`` is on stabilization and bug fixes.
Finally, the vX.Y gets released, and the whole cycle starts over.
netdev patch review
-------------------
.. _patch_status:
Patch status
~~~~~~~~~~~~
Status of a patch can be checked by looking at the main patchwork
queue for netdev:
https://patchwork.kernel.org/project/netdevbpf/list/
The "State" field will tell you exactly where things are at with your
patch:
================== =============================================================
Patch state Description
================== =============================================================
New, Under review pending review, patch is in the maintainer’s queue for
review; the two states are used interchangeably (depending on
the exact co-maintainer handling patchwork at the time)
Accepted patch was applied to the appropriate networking tree, this is
usually set automatically by the pw-bot
Needs ACK waiting for an ack from an area expert or testing
Changes requested patch has not passed the review, new revision is expected
with appropriate code and commit message changes
Rejected patch has been rejected and new revision is not expected
Not applicable patch is expected to be applied outside of the networking
subsystem
Awaiting upstream patch should be reviewed and handled by appropriate
sub-maintainer, who will send it on to the networking trees;
patches set to ``Awaiting upstream`` in netdev's patchwork
will usually remain in this state, whether the sub-maintainer
requested changes, accepted or rejected the patch
Deferred patch needs to be reposted later, usually due to dependency
or because it was posted for a closed tree
Superseded new version of the patch was posted, usually set by the
pw-bot
RFC not to be applied, usually not in maintainer’s review queue,
pw-bot can automatically set patches to this state based
on subject tags
================== =============================================================
Patches are indexed by the ``Message-ID`` header of the emails
which carried them so if you have trouble finding your patch append
the value of ``Message-ID`` to the URL above.
Updating patch status
~~~~~~~~~~~~~~~~~~~~~
Contributors and reviewers do not have the permissions to update patch
state directly in patchwork. Patchwork doesn't expose much information
about the history of the state of patches, therefore having multiple
people update the state leads to confusion.
Instead of delegating patchwork permissions netdev uses a simple mail
bot which looks for special commands/lines within the emails sent to
the mailing list. For example to mark a series as Changes Requested
one needs to send the following line anywhere in the email thread::
pw-bot: changes-requested
As a result the bot will set the entire series to Changes Requested.
This may be useful when author discovers a bug in their own series
and wants to prevent it from getting applied.
The use of the bot is entirely optional, if in doubt ignore its existence
completely. Maintainers will classify and update the state of the patches
themselves. No email should ever be sent to the list with the main purpose
of communicating with the bot, the bot commands should be seen as metadata.
The use of the bot is restricted to authors of the patches (the ``From:``
header on patch submission and command must match!), maintainers of
the modified code according to the MAINTAINERS file (again, ``From:``
must match the MAINTAINERS entry) and a handful of senior reviewers.
Bot records its activity here:
https://netdev.bots.linux.dev/pw-bot.html
Review timelines
~~~~~~~~~~~~~~~~
Generally speaking, the patches get triaged quickly (in less than
48h). But be patient, if your patch is active in patchwork (i.e. it's
listed on the project's patch list) the chances it was missed are close to zero.
The high volume of development on netdev makes reviewers move on
from discussions relatively quickly. New comments and replies
are very unlikely to arrive after a week of silence. If a patch
is no longer active in patchwork and the thread went idle for more
than a week - clarify the next steps and/or post the next version.
For RFC postings specifically, if nobody responded in a week - reviewers
either missed the posting or have no strong opinions. If the code is ready,
repost as a PATCH.
Emails saying just "ping" or "bump" are considered rude. If you can't figure
out the status of the patch from patchwork or where the discussion has
landed - describe your best guess and ask if it's correct. For example::
I don't understand what the next steps are. Person X seems to be unhappy
with A, should I do B and repost the patches?
.. _Changes requested:
Changes requested
~~~~~~~~~~~~~~~~~
Patches :ref:`marked<patch_status>` as ``Changes Requested`` need
to be revised. The new version should come with a change log,
preferably including links to previous postings, for example::
[PATCH net-next v3] net: make cows go moo
Even users who don't drink milk appreciate hearing the cows go "moo".
The amount of mooing will depend on packet rate so should match
the diurnal cycle quite well.
Signed-off-by: Joe Defarmer <joe@barn.org>
---
v3:
- add a note about time-of-day mooing fluctuation to the commit message
v2: https://lore.kernel.org/netdev/123themessageid@barn.org/
- fix missing argument in kernel doc for netif_is_bovine()
- fix memory leak in netdev_register_cow()
v1: https://lore.kernel.org/netdev/456getstheclicks@barn.org/
The commit message should be revised to answer any questions reviewers
had to ask in previous discussions. Occasionally the update of
the commit message will be the only change in the new version.
Partial resends
~~~~~~~~~~~~~~~
Please always resend the entire patch series and make sure you do number your
patches such that it is clear this is the latest and greatest set of patches
that can be applied. Do not try to resend just the patches which changed.
Handling misapplied patches
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Occasionally a patch series gets applied before receiving critical feedback,
or the wrong version of a series gets applied.
Making the patch disappear once it is pushed out is not possible, the commit
history in netdev trees is immutable.
Please send incremental versions on top of what has been merged in order to fix
the patches the way they would look like if your latest patch series was to be
merged.
In cases where full revert is needed the revert has to be submitted
as a patch to the list with a commit message explaining the technical
problems with the reverted commit. Reverts should be used as a last resort,
when original change is completely wrong; incremental fixes are preferred.
Stable tree
~~~~~~~~~~~
While it used to be the case that netdev submissions were not supposed
to carry explicit ``CC: stable@vger.kernel.org`` tags that is no longer
the case today. Please follow the standard stable rules in
:ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>`,
and make sure you include appropriate Fixes tags!
Security fixes
~~~~~~~~~~~~~~
Do not email netdev maintainers directly if you think you discovered
a bug that might have possible security implications.
The current netdev maintainer has consistently requested that
people use the mailing lists and not reach out directly. If you aren't
OK with that, then perhaps consider mailing security@kernel.org or
reading about http://oss-security.openwall.org/wiki/mailing-lists/distros
as possible alternative mechanisms.
Co-posting changes to user space components
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
User space code exercising kernel features should be posted
alongside kernel patches. This gives reviewers a chance to see
how any new interface is used and how well it works.
When user space tools reside in the kernel repo itself all changes
should generally come as one series. If series becomes too large
or the user space project is not reviewed on netdev include a link
to a public repo where user space patches can be seen.
In case user space tooling lives in a separate repository but is
reviewed on netdev (e.g. patches to ``iproute2`` tools) kernel and
user space patches should form separate series (threads) when posted
to the mailing list, e.g.::
[PATCH net-next 0/3] net: some feature cover letter
└─ [PATCH net-next 1/3] net: some feature prep
└─ [PATCH net-next 2/3] net: some feature do it
└─ [PATCH net-next 3/3] selftest: net: some feature
[PATCH iproute2-next] ip: add support for some feature
Posting as one thread is discouraged because it confuses patchwork
(as of patchwork 2.2.2).
Co-posting selftests
~~~~~~~~~~~~~~~~~~~~
Selftests should be part of the same series as the code changes.
Specifically for fixes both code change and related test should go into
the same tree (the tests may lack a Fixes tag, which is expected).
Mixing code changes and test changes in a single commit is discouraged.
Preparing changes
-----------------
Attention to detail is important. Re-read your own work as if you were the
reviewer. You can start with using ``checkpatch.pl``, perhaps even with
the ``--strict`` flag. But do not be mindlessly robotic in doing so.
If your change is a bug fix, make sure your commit log indicates the
end-user visible symptom, the underlying reason as to why it happens,
and then if necessary, explain why the fix proposed is the best way to
get things done. Don't mangle whitespace, and as is common, don't
mis-indent function arguments that span multiple lines. If it is your
first patch, mail it to yourself so you can test apply it to an
unpatched tree to confirm infrastructure didn't mangle it.
Finally, go back and read
:ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
to be sure you are not repeating some common mistake documented there.
Indicating target tree
~~~~~~~~~~~~~~~~~~~~~~
To help maintainers and CI bots you should explicitly mark which tree
your patch is targeting. Assuming that you use git, use the prefix
flag::
git format-patch --subject-prefix='PATCH net-next' start..finish
Use ``net`` instead of ``net-next`` (always lower case) in the above for
bug-fix ``net`` content.
Dividing work into patches
~~~~~~~~~~~~~~~~~~~~~~~~~~
Put yourself in the shoes of the reviewer. Each patch is read separately
and therefore should constitute a comprehensible step towards your stated
goal.
Avoid sending series longer than 15 patches. Larger series takes longer
to review as reviewers will defer looking at it until they find a large
chunk of time. A small series can be reviewed in a short time, so Maintainers
just do it. As a result, a sequence of smaller series gets merged quicker and
with better review coverage. Re-posting large series also increases the mailing
list traffic.
.. _rcs:
Local variable ordering ("reverse xmas tree", "RCS")
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Netdev has a convention for ordering local variables in functions.
Order the variable declaration lines longest to shortest, e.g.::
struct scatterlist *sg;
struct sk_buff *skb;
int err, i;
If there are dependencies between the variables preventing the ordering
move the initialization out of line.
Format precedence
~~~~~~~~~~~~~~~~~
When working in existing code which uses nonstandard formatting make
your code follow the most recent guidelines, so that eventually all code
in the domain of netdev is in the preferred format.
Using device-managed and cleanup.h constructs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Netdev remains skeptical about promises of all "auto-cleanup" APIs,
including even ``devm_`` helpers, historically. They are not the preferred
style of implementation, merely an acceptable one.
Use of ``guard()`` is discouraged within any function longer than 20 lines,
``scoped_guard()`` is considered more readable. Using normal lock/unlock is
still (weakly) preferred.
Low level cleanup constructs (such as ``__free()``) can be used when building
APIs and helpers, especially scoped iterators. However, direct use of
``__free()`` within networking core and drivers is discouraged.
Similar guidance applies to declaring variables mid-function.
Clean-up patches
~~~~~~~~~~~~~~~~
Netdev discourages patches which perform simple clean-ups, which are not in
the context of other work. For example:
* Addressing ``checkpatch.pl``, and other trivial coding style warnings
* Addressing :ref:`Local variable ordering<rcs>` issues
* Conversions to device-managed APIs (``devm_`` helpers)
This is because it is felt that the churn that such changes produce comes
at a greater cost than the value of such clean-ups.
Conversely, spelling and grammar fixes are not discouraged.
Resending after review
~~~~~~~~~~~~~~~~~~~~~~
Allow at least 24 hours to pass between postings. This will ensure reviewers
from all geographical locations have a chance to chime in. Do not wait
too long (weeks) between postings either as it will make it harder for reviewers
to recall all the context.
Make sure you address all the feedback in your new posting. Do not post a new
version of the code if the discussion about the previous version is still
ongoing, unless directly instructed by a reviewer.
The new version of patches should be posted as a separate thread,
not as a reply to the previous posting. Change log should include a link
to the previous posting (see :ref:`Changes requested`).
Testing
-------
Expected level of testing
~~~~~~~~~~~~~~~~~~~~~~~~~
At the very minimum your changes must survive an ``allyesconfig`` and an
``allmodconfig`` build with ``W=1`` set without new warnings or failures.
Ideally you will have done run-time testing specific to your change,
and the patch series contains a set of kernel selftest for
``tools/testing/selftests/net`` or using the KUnit framework.
You are expected to test your changes on top of the relevant networking
tree (``net`` or ``net-next``) and not e.g. a stable tree or ``linux-next``.
patchwork checks
~~~~~~~~~~~~~~~~
Checks in patchwork are mostly simple wrappers around existing kernel
scripts, the sources are available at:
https://github.com/linux-netdev/nipa/tree/master/tests
**Do not** post your patches just to run them through the checks.
You must ensure that your patches are ready by testing them locally
before posting to the mailing list. The patchwork build bot instance
gets overloaded very easily and netdev@vger really doesn't need more
traffic if we can help it.
netdevsim
~~~~~~~~~
``netdevsim`` is a test driver which can be used to exercise driver
configuration APIs without requiring capable hardware.
Mock-ups and tests based on ``netdevsim`` are strongly encouraged when
adding new APIs, but ``netdevsim`` in itself is **not** considered
a use case/user. You must also implement the new APIs in a real driver.
We give no guarantees that ``netdevsim`` won't change in the future
in a way which would break what would normally be considered uAPI.
``netdevsim`` is reserved for use by upstream tests only, so any
new ``netdevsim`` features must be accompanied by selftests under
``tools/testing/selftests/``.
Supported status for drivers
----------------------------
.. note: The following requirements apply only to Ethernet NIC drivers.
Netdev defines additional requirements for drivers which want to acquire
the ``Supported`` status in the MAINTAINERS file. ``Supported`` drivers must
be running all upstream driver tests and reporting the results twice a day.
Drivers which do not comply with this requirement should use the ``Maintained``
status. There is currently no difference in how ``Supported`` and ``Maintained``
drivers are treated upstream.
The exact rules a driver must follow to acquire the ``Supported`` status:
1. Must run all tests under ``drivers/net`` and ``drivers/net/hw`` targets
of Linux selftests. Running and reporting private / internal tests is
also welcome, but upstream tests are a must.
2. The minimum run frequency is once every 12 hours. Must test the
designated branch from the selected branch feed. Note that branches
are auto-constructed and exposed to intentional malicious patch posting,
so the test systems must be isolated.
3. Drivers supporting multiple generations of devices must test at
least one device from each generation. A testbed manifest (exact
format TBD) should describe the device models tested.
4. The tests must run reliably, if multiple branches are skipped or tests
are failing due to execution environment problems the ``Supported``
status will be withdrawn.
5. Test failures due to bugs either in the driver or the test itself,
or lack of support for the feature the test is targgeting are
*not* a basis for losing the ``Supported`` status.
netdev CI will maintain an official page of supported devices, listing their
recent test results.
The driver maintainer may arrange for someone else to run the test,
there is no requirement for the person listed as maintainer (or their
employer) to be responsible for running the tests. Collaboration between
vendors, hosting GH CI, other repos under linux-netdev, etc. is most welcome.
See https://github.com/linux-netdev/nipa/wiki for more information about
netdev CI. Feel free to reach out to maintainers or the list with any questions.
Reviewer guidance
-----------------
Reviewing other people's patches on the list is highly encouraged,
regardless of the level of expertise. For general guidance and
helpful tips please see :ref:`development_advancedtopics_reviews`.
It's safe to assume that netdev maintainers know the community and the level
of expertise of the reviewers. The reviewers should not be concerned about
their comments impeding or derailing the patch flow.
Less experienced reviewers are highly encouraged to do more in-depth
review of submissions and not focus exclusively on trivial or subjective
matters like code formatting, tags etc.
Testimonials / feedback
-----------------------
Some companies use peer feedback in employee performance reviews.
Please feel free to request feedback from netdev maintainers,
especially if you spend significant amount of time reviewing code
and go out of your way to improve shared infrastructure.
The feedback must be requested by you, the contributor, and will always
be shared with you (even if you request for it to be submitted to your
manager).
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
Netdev 제출 규칙 요약과 범위
1-33- Patch 대상 tree를 [PATCH net] 또는 [PATCH net-next]로 명시한다.
- Fix patch에는 어느 tree를 향하든 Fixes: tag가 필수다.
- 15개를 넘는 큰 series를 보내지 말고 더 작은 묶음으로 나눈다.
- 24시간 안에 같은 patch를 다시 게시하지 않는다.
- Local variable은 reverse Christmas tree 순서로 선언한다.
Netdev는 Linux networking 관련 작업 전체를 위한 mailing list다. Linux source tree의 net/ 아래 IPv6 같은 core code와 drivers/net 아래 hardware-specific driver가 포함된다. Traffic이 많은 wireless driver 같은 일부 subsystem은 별도 mailing list와 tree를 갖는다.
그런 별도 subsystem을 제외하면 networking 관련 Linux development의 RFC, review, comment 등은 netdev에서 진행된다. List는 kernel.org에 있으며 archive는 lore.kernel.org/netdev에서 볼 수 있다.
Development cycle과 net·net-next tree
35-106새 Linux release는 main maintainer가 새 code를 Linus의 mainline으로 보내는 2주 merge window로 시작한다. Window가 닫히면 -rc1 tag가 붙고 이후에는 새 feature가 아니라 rc1 content의 fix만 mainline에 들어간다. 약 일주일 단위로 rc2부터 보통 rc7까지 이어지며 조용하면 rc6, 변화가 많으면 rc8까지 갈 수 있다. 마지막 vX.Y-rcN 약 일주일 뒤 official vX.Y가 release된다.
Current cycle 위치는 Linus mainline page의 tags 첫 부분으로 판단할 수 있다. rc1이면 cycle 초반이고 rc7이 일주일 전에 tag되었다면 final release가 임박했을 가능성이 높다. 가장 최근 tag가 -rcN suffix 없는 final release라면 대개 merge window이며 net-next는 닫혀 있다.
Networking에는 David Miller가 이끌던 두 Git repository가 있다. net tree는 Linus mainline의 기존 code에 대한 fix용이고 net-next는 future release의 새 code용이다.
Merge window가 시작되면 지난 약 10주간 net-next에 모인 feature가 vX.Y용 pull request로 mainline에 전달되고 net-next는 닫힌다. net은 해당 content의 fix를 계속 모아 주 단위로 Linus에게 보낸다.
Merge window 시작에 net-next는 새 change와 feature를 받지 않는다. 지난 약 10주간 누적한 content를 vX.Y pull request로 mainline에 넘기고, 동시에 net은 이 content를 위한 fix를 모으기 시작한다. Netdev에 close 공지가 나가지만 cycle을 알면 미리 예측할 수 있다.
net-next가 닫힌 기간에는 새 net-next content를 netdev로 보내지 않는다. Review만을 위한 RFC는 언제든 환영하며 git format-patch에 --subject-prefix='RFC net-next'를 사용한다.
git format-patch --subject-prefix='RFC net-next' start..finish2주가 지나 vX.Y-rc1이 나온 직후 net-next가 다시 열려 vX.Y+1 content를 모은다. Subscribe하지 않았거나 reopen 여부가 불확실하면 net-next repository의 새 networking commit 또는 status website를 확인한다. Net은 vX.Y stabilization과 bug fix를 계속 모아 약 주 단위로 Linus에게 전달한다. Final vX.Y가 release되면 cycle이 반복된다.
Patchwork state와 pw-bot
108-187Patch 상태는 netdev main patchwork queue에서 확인한다. Email의 Message-ID header로 index되므로 찾기 어렵다면 queue URL 뒤에 Message-ID 값을 붙인다.
| Patch state | 의미 |
|---|---|
| New / Under review | Review 대기 중이며 maintainer queue에 있다. 당시 patchwork를 다루는 co-maintainer에 따라 두 state를 같은 뜻으로 사용한다. |
| Accepted | 적절한 networking tree에 적용되었다. 보통 pw-bot이 자동 설정한다. |
| Needs ACK | 해당 영역 expert의 ack 또는 test 결과를 기다린다. |
| Changes requested | Review를 통과하지 못했다. Code와 commit message를 고친 새 revision이 필요하다. |
| Rejected | 거절되었으며 새 revision을 기대하지 않는다. |
| Not applicable | Networking subsystem 밖에서 적용될 것으로 예상한다. |
| Awaiting upstream | 적절한 sub-maintainer가 review·처리한 뒤 networking tree로 보낼 patch다. Netdev patchwork에서는 sub-maintainer가 변경 요청·accept·reject해도 보통 이 state에 남는다. |
| Deferred | Dependency가 있거나 닫힌 tree를 대상으로 게시되어 나중에 다시 보내야 한다. |
| Superseded | 새 version이 게시되었다. 보통 pw-bot이 설정한다. |
| RFC | 적용 대상이 아니며 보통 maintainer review queue에 없다. Subject tag를 보고 pw-bot이 자동 설정할 수 있다. |
Contributor와 reviewer는 patchwork state를 직접 바꿀 권한이 없다. Patchwork가 state history를 충분히 보여 주지 않으므로 여러 사람이 바꾸면 혼란이 생긴다. 대신 netdev는 list email 안의 특별한 command line을 읽는 mail bot을 사용한다.
pw-bot: changes-requestedThread 어디에든 위 line을 보내면 bot이 series 전체를 Changes Requested로 바꾼다. Author가 자기 series에서 bug를 찾아 적용을 막고 싶을 때 유용하다.
Bot 사용은 완전히 선택 사항이다. 확신이 없으면 존재를 무시해도 maintainer가 직접 분류한다. Bot과 통신할 목적만으로 list에 email을 보내서는 안 되며 command는 metadata로 취급한다.
Bot command는 patch author, MAINTAINERS에 기록된 수정 code의 maintainer, 소수 senior reviewer만 사용할 수 있다. Patch submission의 From:과 command sender가 일치해야 하며 maintainer도 From:이 MAINTAINERS entry와 일치해야 한다.
Review 시간과 Changes Requested 대응
189-240Patch는 일반적으로 48시간 안에 빠르게 triage된다. Patchwork project list에 active 상태로 보인다면 누락되었을 가능성은 거의 없으므로 기다린다.
Netdev 개발량이 많아 reviewer는 discussion에서 비교적 빨리 다음 작업으로 이동한다. 일주일 동안 조용했다면 새 comment나 reply가 올 가능성은 매우 낮다. Patch가 patchwork에서 더 이상 active하지 않고 thread도 일주일 넘게 멈췄다면 다음 단계를 확인하거나 새 version을 게시한다.
RFC에 일주일 동안 응답이 없다면 reviewer가 놓쳤거나 강한 의견이 없는 경우다. Code가 준비되었다면 PATCH로 다시 게시한다. 단순히 ping 또는 bump만 적은 email은 무례하게 여겨진다. 상태나 discussion 결론을 알 수 없다면 자신의 최선의 추정을 설명하고 맞는지 묻는다.
I don't understand what the next steps are. Person X seems to be unhappy
with A, should I do B and repost the patches?Changes Requested state의 patch는 수정해야 한다. 새 version에는 가능하면 이전 posting link를 포함한 change log를 넣는다. Commit message도 이전 discussion에서 reviewer가 질문한 내용을 스스로 답하도록 수정한다. 때로는 새 version의 유일한 변경이 commit message 갱신일 수 있다.
[PATCH net-next v3] net: make cows go moo
Even users who don't drink milk appreciate hearing the cows go "moo".
The amount of mooing will depend on packet rate so should match
the diurnal cycle quite well.
Signed-off-by: Joe Defarmer <joe@barn.org>
---
v3:
- add a note about time-of-day mooing fluctuation to the commit message
v2: https://lore.kernel.org/netdev/123themessageid@barn.org/
- fix missing argument in kernel doc for netif_is_bovine()
- fix memory leak in netdev_register_cow()
v1: https://lore.kernel.org/netdev/456getstheclicks@barn.org/Series 재전송, 잘못 적용된 patch와 stable·security
242-284새 revision을 보낼 때는 항상 전체 patch series를 다시 보내고 최신이며 그대로 적용 가능한 묶음임을 번호로 명확히 표시한다. 바뀐 patch만 부분적으로 재전송하지 않는다.
Critical feedback 전에 series가 적용되거나 잘못된 version이 적용될 수 있다. Netdev tree에 push된 commit history는 immutable이므로 patch를 사라지게 할 수 없다. Latest series가 merge되었을 때와 같은 최종 형태가 되도록 이미 merge된 commit 위에 incremental fix를 보낸다.
Full revert가 필요하면 revert 자체를 patch로 list에 제출하고 revert 대상 commit의 technical problem을 commit message에 설명한다. Original change가 완전히 틀린 마지막 수단으로만 revert를 사용하며 incremental fix를 선호한다.
과거에는 netdev submission에 명시적 CC: stable@vger.kernel.org tag를 넣지 않았지만 현재는 그렇지 않다. Documentation/process/stable-kernel-rules.rst의 일반 stable 규칙을 따르고 적절한 Fixes tag를 반드시 넣는다.
Security 영향을 줄 수 있는 bug를 발견했다고 생각해도 netdev maintainer에게 직접 email하지 않는다. Current netdev maintainer는 direct contact 대신 mailing list 사용을 지속적으로 요청했다. 이에 동의하기 어렵다면 security@kernel.org 또는 distros security list 같은 대안을 검토한다.
User-space tool과 selftest를 함께 게시하는 방법
287-320Kernel feature를 사용하는 user-space code는 kernel patch와 함께 게시해야 reviewer가 새 interface의 사용 방법과 실제 동작 품질을 볼 수 있다.
User-space tool이 kernel repository 안에 있다면 일반적으로 모든 변경을 하나의 series로 보낸다. Series가 너무 크거나 user-space project가 netdev에서 review되지 않는다면 user-space patch를 볼 수 있는 public repository link를 포함한다.
User-space tooling이 별도 repository에 있지만 iproute2처럼 netdev에서 review되는 경우 kernel과 user-space patch를 각각 별도 series와 thread로 게시한다.
Kernel feature 준비·구현·selftest는 하나의 net-next series로 묶고, iproute2 지원은 독립 series로 게시한다. 하나의 thread로 섞으면 patchwork 2.2.2 기준으로 혼동을 일으킨다.
Selftest는 code change와 같은 series에 포함한다. Fix의 경우 code와 관련 test가 같은 tree로 가야 하며 test에 Fixes tag가 없는 것은 정상이다. 다만 code change와 test change를 하나의 commit에 섞는 것은 권장하지 않는다.
Patch 준비, 대상 tree와 series 크기
322-364세부 사항을 꼼꼼히 확인하고 reviewer 시점에서 자기 작업을 다시 읽는다. checkpatch.pl을 사용하고 필요하면 --strict도 써 볼 수 있지만 결과를 생각 없이 기계적으로 따르지는 않는다.
Bug fix commit log에는 user에게 보이는 symptom, 그 현상이 생기는 근본 원인, 필요하면 제안한 fix가 최선인 이유를 적는다. Whitespace를 망가뜨리지 말고 여러 line에 걸친 function argument indentation도 틀리지 않는다. 첫 patch라면 자신에게 mail로 보내 unpatched tree에 test apply하여 전송 infrastructure가 내용을 변형하지 않았는지 확인한다. 마지막으로 Documentation/process/submitting-patches.rst를 다시 읽어 흔한 실수를 반복하지 않았는지 점검한다.
Maintainer와 CI bot을 돕기 위해 대상 tree를 subject에 명시한다. 새 feature는 다음 명령처럼 net-next를 사용하고 bug fix는 항상 lower-case net으로 바꾼다.
git format-patch --subject-prefix='PATCH net-next' start..finish각 patch는 독립적으로 읽히므로 stated goal을 향하는 이해 가능한 한 단계여야 한다. 15개를 넘는 series는 피한다. 큰 series는 reviewer가 긴 시간을 확보할 때까지 미루기 쉽지만 작은 series는 짧은 시간에 review할 수 있어 더 빨리 merge되고 review coverage도 좋아진다. 큰 series를 반복 게시하면 mailing list traffic도 늘어난다.
Reverse Christmas tree와 cleanup 정책
366-417Netdev function local variable은 declaration line 길이가 긴 것부터 짧은 순서로 정렬하는 reverse Christmas tree(RCS) convention을 사용한다.
struct scatterlist *sg;
struct sk_buff *skb;
int err, i;Variable 사이 dependency 때문에 순서를 맞출 수 없다면 initialization을 declaration 밖으로 옮긴다. Nonstandard formatting을 사용하는 기존 code에서 작업할 때도 새 code는 최신 guideline을 따라 netdev 영역 전체가 점차 preferred format으로 수렴하게 한다.
Netdev는 역사적으로 devm_ helper를 포함한 모든 auto-cleanup API 약속에 회의적이다. 이런 구현은 preferred style이 아니라 허용 가능한 style일 뿐이다.
- 20 line보다 긴 function 안에서 guard() 사용은 권장하지 않으며 scoped_guard()가 더 읽기 쉽다고 본다.
- 일반적인 lock/unlock을 여전히 약하게나마 더 선호한다.
- __free() 같은 low-level cleanup construct는 API·helper, 특히 scoped iterator를 만들 때 사용할 수 있다.
- Networking core와 driver에서 __free()를 직접 사용하는 것은 권장하지 않는다.
- Function 중간 variable declaration에도 비슷한 지침이 적용된다.
다른 작업과 무관한 단순 cleanup patch도 권장하지 않는다. checkpatch.pl과 trivial coding-style warning 수정, RCS 정렬만 고치는 변경, devm_ API conversion이 예다. 이런 churn 비용이 cleanup 가치보다 크다고 보기 때문이다. 반면 spelling과 grammar fix는 억제하지 않는다.
Review 뒤 새 version 게시 간격
419-433Posting 사이에는 최소 24시간을 둔다. 모든 geographic location의 reviewer가 의견을 낼 시간을 보장하기 위해서다. 반대로 몇 주씩 너무 오래 기다리면 context를 기억하기 어려워진다.
새 posting은 모든 feedback에 대응해야 한다. Reviewer가 직접 지시하지 않았다면 이전 version discussion이 진행 중인 동안 새 code version을 게시하지 않는다. 새 version은 이전 posting의 reply가 아니라 별도 thread로 보내고 change log에는 이전 posting link를 포함한다.
Build·runtime test와 patchwork check
435-463최소한 W=1을 설정한 allyesconfig와 allmodconfig build를 새 warning이나 failure 없이 통과해야 한다. 이상적으로는 변경에 특화된 runtime test도 수행하고 patch series에 tools/testing/selftests/net용 kernel selftest 또는 KUnit test를 포함한다.
make W=1 allyesconfig
make W=1
make W=1 allmodconfig
make W=1위 build command 전개는 원문의 요구 조건을 실행 형태로 풀어 쓴 예시다. Architecture와 build output directory 등은 실제 test 환경에 맞게 지정한다.
Stable tree나 linux-next가 아니라 관련 networking tree인 net 또는 net-next 위에서 변경을 test해야 한다.
Patchwork check는 대부분 기존 kernel script를 감싼 단순 wrapper다. Check만 돌리기 위해 patch를 게시해서는 절대 안 된다. Mailing list에 보내기 전에 local test로 준비 상태를 확인해야 한다. Patchwork build bot은 쉽게 과부하되고 불필요한 netdev traffic도 피해야 한다.
netdevsim의 역할과 한계
465-479netdevsim은 실제 capable hardware 없이 driver configuration API를 실행해 볼 수 있는 test driver다. 새 API를 추가할 때 netdevsim 기반 mock-up과 test를 강하게 권장한다.
하지만 netdevsim 자체는 use case나 user로 인정되지 않는다. 새 API를 실제 driver에도 구현해야 한다. 보통 uAPI라면 break로 볼 만한 방식으로 netdevsim이 future에 바뀌지 않으리라는 보장도 없다.
Netdevsim은 upstream test 전용이므로 새 netdevsim feature에는 tools/testing/selftests/ 아래 selftest가 반드시 따라야 한다.
Ethernet NIC driver의 Supported 상태 요건
481-525다음 요구는 Ethernet NIC driver에만 적용된다. MAINTAINERS에서 Supported 상태를 받으려는 driver는 모든 upstream driver test를 실행하고 하루 두 번 결과를 보고해야 한다. 따르지 않으면 Maintained 상태를 사용한다. 현재 upstream 처리 방식에서 Supported와 Maintained 사이 차이는 없다.
- Linux selftests의 drivers/net과 drivers/net/hw target 아래 모든 test를 실행해야 한다. Private·internal test report도 환영하지만 upstream test는 필수다.
- 최소 12시간마다 한 번 실행한다. 선택한 branch feed의 지정 branch를 test한다. Branch가 자동 구성되고 의도적으로 malicious한 patch posting에 노출되므로 test system을 격리해야 한다.
- 여러 device generation을 지원하는 driver는 generation마다 최소 한 장치를 test한다. Testbed manifest의 정확한 형식은 미정이지만 test한 model을 기술해야 한다.
- Test는 안정적으로 실행되어야 한다. Execution environment 문제로 여러 branch를 건너뛰거나 test가 실패하면 Supported 상태를 회수한다.
- Driver 또는 test 자체의 bug, test 대상 feature 미지원으로 생긴 failure는 Supported 상태를 잃는 근거가 아니다.
Netdev CI는 supported device와 최근 test result를 보여 주는 official page를 유지한다. Driver maintainer가 다른 사람에게 test 실행을 맡겨도 되며 MAINTAINERS에 적힌 사람이나 고용주가 직접 실행해야 한다는 요구는 없다. Vendor 협업, hosted GitHub CI, linux-netdev 아래 다른 repository 사용 등을 환영한다.
Reviewer guidance와 peer feedback
527-552Expertise 수준과 관계없이 list에서 다른 사람의 patch를 review하는 것을 강하게 권장한다. 일반 지침과 tip은 development_advancedtopics_reviews를 참고한다.
Netdev maintainer는 community와 reviewer의 expertise 수준을 알고 있다고 가정해도 된다. Reviewer는 자기 comment가 patch 흐름을 방해하거나 탈선시킬까 걱정하지 않아도 된다.
경험이 적은 reviewer일수록 formatting이나 tag처럼 trivial하거나 주관적인 문제만 보지 말고 submission을 더 깊게 review하도록 강하게 권장한다.
일부 회사는 employee performance review에 peer feedback을 사용한다. Code review에 많은 시간을 쓰거나 shared infrastructure 개선을 위해 특별히 노력했다면 netdev maintainer에게 feedback을 요청할 수 있다. Contributor 본인이 요청해야 하며 manager에게 제출해 달라고 요청하더라도 feedback 내용은 항상 contributor와 공유된다.
Netdev 개발 cycle과 tree
maintainer-netdev.rst:6-107Networking은 current-cycle fix와 next-cycle feature를 별도 tree·branch로 관리한다. Patch subject와 cover letter에서 target tree를 명확히 하고 netdev list에서 public review를 거쳐 patchwork와 maintainer queue로 이동한다.
Merge window 상태에 따라 feature tree가 닫히거나 fix 기준이 엄격해질 수 있으므로 netdev status와 tree announcement를 확인한다. 다른 subsystem dependency는 immutable branch 또는 합의된 merge ordering으로 처리한다.