mirror of
https://gitlab.freedesktop.org/NetworkManager/NetworkManager
synced 2024-07-03 08:08:46 +00:00
Add more detailed explanations for users, contributors and maintainers
README.md: As this document is mainly for normal users, and in Gitlab it's displayed by default, it's the main entry point to get information when someone get into the repo, either via web or cloned. Added explanations about how to install and use NM and how to find the documentation for users. Added brief info about how to report issues and ask for help, with links to CONTRIBUTING.md to get more details. Added brief link for potential contributors to read CONTRIBUTING.md. People not familiar with open source projects might not be aware of it. Deleted the "moved to freedesktop" message. After 15 years, people might know yet. Added brief explanation about the free software license. CONTRIBUTING.md: Added a link to the list of all communication channels, only mailing list and IRC were listed. Added detailed explanation about how to report issues and attach logs. It also references the new tool anonymize-logs.py. Added brief guidelines about how to start contributing choosing issues from the tracker. Fixed some small formatting issues and added a reference to nm-in-vm, fixing the link to nm-in-container too. MAINTAINERS.md: Added explanation about how to triage and properly label the issues. This is basically based on the kind-of-workflow that we already have, but maybe it's a good time to check that it's correct or to propose small changes (so, please propose changes in review).
This commit is contained in:
Íñigo Huguet
Íñigo Huguet
parent
69ceee1a0b
commit
5481ba1568
|
|
@ -9,13 +9,62 @@ Check out website https://networkmanager.dev and our [GNOME page](https://wiki.g
|
|||
|
||||
The release tarballs can be found at [download.gnome.org](https://download.gnome.org/sources/NetworkManager/).
|
||||
|
||||
Our mailing list is networkmanager@lists.freedesktop.org ([archive](https://lists.freedesktop.org/archives/networkmanager/),
|
||||
[old-archive](https://mail.gnome.org/archives/networkmanager-list/)).
|
||||
Find our available communication channels at https://networkmanager.dev/community/.
|
||||
|
||||
Find us on IRC channel `#nm` on Libera.Chat.
|
||||
|
||||
Report issues and send patches via [gitlab.freedesktop.org](https://gitlab.freedesktop.org/NetworkManager/NetworkManager/)
|
||||
or our mailing list.
|
||||
Report issues
|
||||
-------------
|
||||
|
||||
Report issues or feature requests in our [Gitlab's issue tracker](https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/issues)
|
||||
or our maling list.
|
||||
|
||||
For bug reports usually NetworkManager's logs will be needed to understand the
|
||||
problem. Attach the full logs to the issue. For WiFi related issues, attach also
|
||||
the logs from wpa_supplicant, or iwd if you are using it (i.e.
|
||||
`journalctl -u NetworkManager -u wpa_supplicant`).
|
||||
|
||||
To get more useful logs, increase the log level as explained in
|
||||
["logging SECTION" in NetworkManager.conf](https://networkmanager.dev/docs/api/latest/NetworkManager.conf.html).
|
||||
|
||||
Logfiles contain no passwords and little sensitive information, but please
|
||||
check before posting the file online. The script [anonymize-logs.py](contrib/scripts/anonymize-logs.py)
|
||||
can do some basic data anonymization but makes a bit harder to analyze the logs
|
||||
and you still need to review them. You can also personally hand over the logfile
|
||||
to a NM developer to treat it confidential.
|
||||
|
||||
|
||||
Contribute
|
||||
----------
|
||||
|
||||
Send patches to our repository at [gitlab.freedesktop.org](https://gitlab.freedesktop.org/NetworkManager/NetworkManager/).
|
||||
If you are willing to contribute, please read these guidelines first:
|
||||
|
||||
- Find bugs or features to work on in our [Gitlab's issue tracker](https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/issues).
|
||||
|
||||
- Work on any issue you want, but please put a comment to indicate that you are
|
||||
willing to work on it so others don't do the same work in parallel, or to
|
||||
check whether anyone is already doing so.
|
||||
|
||||
- Issues marked as `help-wanted` are those where the NetworkManager developers
|
||||
are explicitly asking for contributors' help, probably due to lack of capacity
|
||||
to work on it.
|
||||
|
||||
- Issues marked as `good-first-issue` indicate that they are probably quite
|
||||
simple fixes, well suited for first time contributors.
|
||||
|
||||
- Contributions for features or bugs not reported in the issue tracker are also
|
||||
welcome, but if they require a high amount of work, it is always better to
|
||||
open an issue explaining what you intend to do first. That way, you won't
|
||||
waste your valuable time if your idea doesn't fit well into the project or a
|
||||
different approach would be desirable.
|
||||
|
||||
- Reference related issues in your Merge Request description, and if the issue
|
||||
gets resolved with it, indicate it with a line `Resolves: https://issue-url`.
|
||||
Please use full URLs because they are clickable both from the web UI and from
|
||||
the terminal.
|
||||
|
||||
- Read the rest of this document to learn about the code style, code
|
||||
organization, tests and other useful stuff.
|
||||
|
||||
|
||||
Documentation
|
||||
|
|
@ -218,6 +267,7 @@ Code Structure
|
|||
|
||||
`./tools`- tools for generating the intermediate files or merging the file.
|
||||
|
||||
|
||||
Cscope/ctags
|
||||
---------------------------
|
||||
|
||||
|
|
@ -420,6 +470,7 @@ To resync our local notes use:
|
|||
```
|
||||
$ git fetch origin refs/notes/bugs:refs/notes/bugs -f
|
||||
```
|
||||
### Testing NetworkManager with nm-in-container script.
|
||||
|
||||
See [the readme](tools/nm-in-container/README.md) for details.
|
||||
### Testing NetworkManager with nm-in-container or nm-in-vm scripts.
|
||||
|
||||
See [the readme](tools/nm-guest-data/README.md) for details.
|
||||
|
|
|
|||
|
|
@ -1,3 +1,45 @@
|
|||
Triaging issues
|
||||
---------------
|
||||
|
||||
Issue tracker: https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/issues
|
||||
|
||||
Help other maintainers with the triage following these guidelines. This way, it
|
||||
will be easier to find issues that require attention.
|
||||
|
||||
- Assign an issue to yourself if you are going to take care of providing the
|
||||
required help. Assign it to another person if he/she is more suitable to help,
|
||||
but do this quite rarely so we take care of not overloading to anyone.
|
||||
|
||||
- Add suitable labels to indicate the state of open issues:
|
||||
|
||||
- `need-info`: waiting for info or feedback from anyone.
|
||||
|
||||
- `need-discussion`: something is not clear about what to do, or about if
|
||||
something has to be done at all. The problem should be discussed by the
|
||||
maintainers and/or with the reporter and/or other interested parts.
|
||||
|
||||
- `triaged`: if the problem is properly explained and understood. Add also
|
||||
one of the labels `bug` or `RFE` as corresponds.
|
||||
|
||||
- `help-wanted`: request external contributors to work on this. If it's a
|
||||
simple fix, add `good-first-issue` too.
|
||||
|
||||
- `work-in-progress`: anyone is already working on a Merge Request, so others.
|
||||
|
||||
- `blocked`: the issue is waiting for something that blocks its progress
|
||||
|
||||
- `close-proposed`: there are good reasons to reject the request (explain
|
||||
those reasons when adding the label). If after a reasonable time there is no
|
||||
additional info that is good enouch to reconsider it, the issue will be
|
||||
closed.
|
||||
It is not mandatory to always use this tag before closing an issue, but
|
||||
usually desirable.
|
||||
|
||||
- Close an issue if the problem is already solved, either via a code fix or via
|
||||
some information that has been provided. Also if the request is clearly
|
||||
incorrect or doesn't fit at all in the project.
|
||||
|
||||
|
||||
Merging Merge Requests
|
||||
----------------------
|
||||
|
||||
|
|
|
|||
80
README.md
80
README.md
|
|
@ -1,9 +1,5 @@
|
|||
******************
|
||||
NetworkManager core daemon has moved to gitlab.freedesktop.org!
|
||||
|
||||
git clone https://gitlab.freedesktop.org/NetworkManager/NetworkManager.git
|
||||
******************
|
||||
|
||||
NetworkManager
|
||||
==============
|
||||
|
||||
Networking that Just Works
|
||||
--------------------------
|
||||
|
|
@ -31,7 +27,8 @@ network. NetworkManager will _never_ activate a connection that is not in this
|
|||
list, or that the user has not directed NetworkManager to connect to.
|
||||
|
||||
|
||||
How it works:
|
||||
How it works
|
||||
------------
|
||||
|
||||
The NetworkManager daemon runs as a privileged service (since it must access
|
||||
and control hardware), but provides a D-Bus interface on the system bus to
|
||||
|
|
@ -56,7 +53,34 @@ link-local addresses. Most communication with these daemons occurs, again,
|
|||
via D-Bus.
|
||||
|
||||
|
||||
How to use it
|
||||
-------------
|
||||
|
||||
Install NetworkManager with your distribution's package manager.
|
||||
|
||||
As NetworkManager is actually a daemon that runs in the background, you need to
|
||||
use one of the many existing client programs to interact with it.
|
||||
|
||||
Terminal clients:
|
||||
- `nmcli`: advanced command line client that gives you full control over all the
|
||||
aspects of NetworkManager, developed as part of the NetworkManager project.
|
||||
- `nmtui`: text-based user interface (TUI) client. Also for the terminal, but
|
||||
interactive and more user friendly, also part of the NetworkManager project.
|
||||
- [`nmstate`][1]: declarative network API and command line tool that uses
|
||||
NetworkManager as backend.
|
||||
- Ansible: use the [network-role][2] in your playbooks
|
||||
|
||||
GUI clients
|
||||
- `nm-connection-editor` and `nm-applet`: basic GUI interfaces developed by
|
||||
the NetworkManager project.
|
||||
- GNOME shell: interacts with NetworkManager via its default settings panel
|
||||
`gnome-control-center`
|
||||
- KDE Plasma: interacts with NetworkManager via its default settings panel
|
||||
and `plasma-nm`
|
||||
|
||||
|
||||
Why doesn't my network Just Work?
|
||||
---------------------------------
|
||||
|
||||
Driver problems are the #1 cause of why NetworkManager sometimes fails to
|
||||
connect to wireless networks. Often, the driver simply doesn't behave in a
|
||||
|
|
@ -86,3 +110,45 @@ distribution directs syslog's 'daemon' facility output, as
|
|||
enormously. See the logging section of file
|
||||
contrib/fedora/rpm/NetworkManager.conf for how to enable debug logging
|
||||
in NetworkManager.
|
||||
|
||||
|
||||
Documentation
|
||||
-------------
|
||||
|
||||
Updated documentation can be found at https://networkmanager.dev/docs
|
||||
|
||||
Users can consult the man pages. Most relevant pages for normal users are:
|
||||
- NetworkManager daemon: [`NetworkManager (8)`][3], [`NetworkManager.conf (5)`][4]
|
||||
- nmcli: [`nmcli (1)`][5], [`nmcli-examples (5)`][6], [`nm-settings-nmcli (5)`][7]
|
||||
- nmtui: [`nmtui (1)`][8]
|
||||
|
||||
|
||||
Get in touch
|
||||
------------
|
||||
|
||||
To connect with the community, get help or get involved see the available
|
||||
communication channels at https://networkmanager.dev/community/
|
||||
|
||||
Report bugs or feature request in our [issue tracker](https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/issues).
|
||||
See [Report issues](https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/blob/main/CONTRIBUTING.md?ref_type=heads#report-issues)
|
||||
for details about how to do it.
|
||||
|
||||
To get involved, see [CONTRIBUTING.md](CONTRIBUTING.md)
|
||||
|
||||
|
||||
License
|
||||
-------
|
||||
|
||||
NetworkManager is free software under GPL-2.0-or-later and LGPL-2.1-or-later.
|
||||
See [CONTRIBUTING.md#legal](CONTRIBUTING.md#legal) and
|
||||
[RELICENSE.md](RELICENSE.md) for details.
|
||||
|
||||
|
||||
[1]: https://nmstate.io/
|
||||
[2]: https://linux-system-roles.github.io/network/
|
||||
[3]: https://networkmanager.dev/docs/api/latest/NetworkManager.html
|
||||
[4]: https://networkmanager.dev/docs/api/latest/NetworkManager.conf.html
|
||||
[5]: https://networkmanager.dev/docs/api/latest/nmcli.html
|
||||
[6]: https://networkmanager.dev/docs/api/latest/nmcli-examples.html
|
||||
[7]: https://networkmanager.dev/docs/api/latest/nm-settings-nmcli.html
|
||||
[8]: https://networkmanager.dev/docs/api/latest/nmtui.html
|
||||
|
|
|
|||
|
|
@ -648,7 +648,9 @@ level=TRACE
|
|||
domains=ALL
|
||||
</programlisting>
|
||||
and restart the daemon with <command>systemctl restart NetworkManager</command>. Then
|
||||
reproduce the problem. You can find the logs in syslog (for example <command>journalctl</command>).
|
||||
reproduce the problem. You can find the logs in syslog (for example
|
||||
<command>journalctl</command>, or <command>journalctl -u NetworkManager</command>
|
||||
to show only logs from NetworkManager).
|
||||
</para>
|
||||
|
||||
<para>
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user