diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..e9edfe54d --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,102 @@ +# Contribute to virt-manager + +## Bug reporting + +The preferred place for bug reports is bugzilla.redhat.com. This +is documented more at https://virt-manager.org/bugs/ + +Small issues can be reported in the +[github issue tracker](https://github.com/virt-manager/virt-manager/issues). +Anything that's non-trivial, or is a feature request, should be filed in +bugzilla. + +Please only file issues if they apply to the latest version of +virt-manager. If you are using an older version from a distro, +please file a bug with them. + +When filing a bug, please reproduce the issue with the `--debug` +flag passed to the tool and attach the full output in the bug +report. + + +## Writing patches + +The following commands will be useful for anyone writing patches: + +```sh +./setup.py test # Run local unit test suite +./setup.py pylint # Run pylint/pycodestyle checking +``` + +Any patches shouldn't change the output of 'test' or 'pylint'. Depending +on what version of libvirt or pylint is installed, you may see some +pre-existing errors from these commands. The important thing is that +any changes you make do not add additional errors. + +The 'pylint' command requires [`pylint`](https://github.com/PyCQA/pylint) +and [`pycodestyle`](https://github.com/pycqa/pycodestyle) to be installed. +If [`codespell`](https://github.com/codespell-project/codespell) is installed, +it will be invoked as well. + +One useful way to manually test virt-manager's UI is using libvirt's +unit test driver. From the source directory, Launch virt-manager like: +```sh +./virt-manager --connect test://$PWD/tests/testdriver.xml +``` + +This testdriver has many fake XML definitions that can be used to see each bit +of virt-manager's UI. It also enables testing the various wizards without +having to alter your host virt config. + +The command line tools can be tested similarly. To run a virt-install +command that won't alter your host config, you can do: + +```sh +./virt-install --connect test:///default --debug ... +``` + +`--connect test:///default` here is libvirt's built in unit test driver. + +We use [glade-3](https://glade.gnome.org/) for building most of virt-manager's +UI. See the files in the ui/ directory. + + +## Submitting patches + +The [virt-manager git repo](https://github.com/virt-manager/virt-manager) +is hosted on github. Small patches are acceptable via github pull-request, +but anything non-trivial should be sent to the +[virt-tools-list mailing list](https://www.redhat.com/mailman/listinfo/virt-tools-list). + +Sending patches using `git send-email` is preferred, but `git format-patch` +output attached to an email is also fine. + + +## Introductory tasks + +Extending the virt-install or virt-xml command line is a good introductory +task for virt-manager. See [the wiki](https://github.com/virt-manager/virt-manager/wiki) +for both a patch tutorial, and a list of libvirt `` XML options +that still need to be added to our command line. + + +## Translations + +Translations are handled at `fedora.zanata.org`. Please register for a Fedora +account and request access to a translation team, as described at +[Translate on Zanata](https://fedoraproject.org/wiki/L10N/Translate_on_Zanata), +and contribute at +[virt-manager at Zanata](https://fedora.zanata.org/project/view/virt-manager/). + + +## Advanced testing + +There's a few standalone specialty tests: + +```sh +./setup.py test_ui # dogtail UI test suite. This takes over your desktop +./setup.py test_urls # Test fetching media from live distro URLs +./setup.py test_initrd_inject # Test live virt-install --initrd-inject +``` + +All test 'test*' commands have a `--debug` option if you are hitting problems. For more options, see `./setup.py test --help`. diff --git a/HACKING.md b/HACKING.md deleted file mode 100644 index 34f70c19b..000000000 --- a/HACKING.md +++ /dev/null @@ -1,64 +0,0 @@ -# HACKING - -The following commands will be useful for anyone writing patches: -```sh -./setup.py test # Run local unit test suite -./setup.py pylint # Run a pylint script against the codebase -``` - -Any patches shouldn't change the output of 'test' or 'pylint'. The -'pylint' command requires [`pylint`](https://github.com/PyCQA/pylint) and -[`pycodestyle`](https://github.com/pycqa/pycodestyle) to be installed. If -[`codespell`](https://github.com/codespell-project/codespell) is installed, -it will be invoked as well. - -These commands may report false positives, if you think your changes expose -one, please mention it with your patch submission and maintainers will -help you sort it out. - -'test*' have a `--debug` option if you are hitting problems. -For more options, use `./setup.py test --help`. - -One useful way to manually test virt-manager's UI is using libvirt's -unit test driver. From the source directory, Launch virt-manager like: -```sh -virt-manager --connect test://$PWD/tests/testdriver.xml -``` - -This testdriver has many fake XML definitions that can be used to see each bit -of virt-manager's UI. It also enables testing the various wizards without -having to alter your host virt config. - -Also, there's a few standalone specialty tests: -```sh -./setup.py test_urls # Test fetching media from distro URLs -./setup.py test_initrd_inject # Test --initrd-inject -``` - -We use [glade-3](https://glade.gnome.org/) for building virt-manager's UI. -It is recommended you have a fairly recent version of `glade-3`. If a small UI -change seems to rewrite the entire glade file, you likely have a too old -(or too new :) glade version. - -## Submitting patches - -Patches should be developed against a git checkout and **not** a source -release(see [git repository](https://github.com/virt-manager/virt-manager)). - -Patches should be sent to the -[mailing list](https://www.redhat.com/mailman/listinfo/virt-tools-list). - -Using git format-patch/send-email is preferred, but an attachment with -format-patch output is fine too. - -Small patches are acceptable via github pull-request, but anything -non-trivial should be sent to the mailing list. - -## Translations - -Translations are handled at `fedora.zanata.org`. Please register for a Fedora -account and request access to a translation team, as described at -[Translate on Zanata](https://fedoraproject.org/wiki/L10N/Translate_on_Zanata). - -And contribute to -[virt-manager at Zanata](https://fedora.zanata.org/project/view/virt-manager/). diff --git a/MANIFEST.in b/MANIFEST.in index adb3e4b76..b4acb9bac 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,5 +1,5 @@ # to be included/excluded from the tarball produced by sdist -include COPYING HACKING.md INSTALL.md NEWS.md README.md +include COPYING CONTRIBUTING.md INSTALL.md NEWS.md README.md include MANIFEST.in include setup.py include virt-* diff --git a/README.md b/README.md index 78ffecbc1..c0b5da4b4 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,9 @@ # Virtual Machine Manager -This application provides a graphical tool for managing virtual machines -via the [libvirt](https://libvirt.org) library. - -The front end of the application uses the GTK / Glade libraries for -all user interaction components. The back end uses libvirt for managing -Qemu/KVM and Xen virtual machines, as well as LXC containers. The UI is -primarily tested with KVM, but is intended to be reasonably portable to any -virtualization backend libvirt supports. +`virt-manager` is a graphical tool for managing virtual machines +via [libvirt](https://libvirt.org). Most usage is with QEMU/KVM +virtual machines, but Xen and libvirt LXC containers are well +supported. Common operations for any libvirt driver should work. Several command line tools are also provided: @@ -17,7 +13,12 @@ Several command line tools are also provided: - `virt-convert`: Convert VMX or OVF configs to libvirt virtual machines For dependency info and installation instructions, see the -[INSTALL.md](INSTALL.md) file. +[INSTALL.md](INSTALL.md) file. If you just want to quickly test the +code from a git checkout, you can launch any of the commands like: + +```sh +./virt-manager --debug ... +``` ## Contact @@ -26,8 +27,8 @@ For dependency info and installation instructions, see the mailing list. - For IRC we use #virt on OFTC. - For bug reporting info, see - [BugReporting](https://virt-manager.org/page/BugReporting). + [virt-manager bug reporting](https://virt-manager.org/bugs). - There are further project details on the [virt-manager](https://virt-manager.org/) website. - - See the [HACKING.md](HACKING.md) file for info about submitting patches or + - See the [CONTRIBUTING.md](CONTRIBUTING.md) file for info about submitting patches or contributing translations. diff --git a/man/virt-clone.pod b/man/virt-clone.pod index c8678dc27..0cd79a42c 100644 --- a/man/virt-clone.pod +++ b/man/virt-clone.pod @@ -203,7 +203,7 @@ new guest can do a filesystem resize when it boots. =head1 BUGS -Please see https://virt-manager.org/page/BugReporting +Please see L =head1 COPYRIGHT diff --git a/man/virt-convert.pod b/man/virt-convert.pod index ca44a01c8..8bb02ad79 100644 --- a/man/virt-convert.pod +++ b/man/virt-convert.pod @@ -127,7 +127,7 @@ Convert the specified .vmx file. Any references disk images must be in the same =head1 BUGS -Please see https://virt-manager.org/page/BugReporting +Please see L =head1 COPYRIGHT diff --git a/man/virt-install.pod b/man/virt-install.pod index 76d3acd3b..fbc8dbfb5 100644 --- a/man/virt-install.pod +++ b/man/virt-install.pod @@ -1756,7 +1756,7 @@ Start serial QEMU ARM VM, which requires specifying a manual kernel. =head1 BUGS -Please see https://virt-manager.org/page/BugReporting +Please see L =head1 COPYRIGHT diff --git a/man/virt-xml.pod b/man/virt-xml.pod index a24a04fa7..834eae1dd 100644 --- a/man/virt-xml.pod +++ b/man/virt-xml.pod @@ -384,7 +384,7 @@ Virtualization hosts supported by libvirt may not permit all changes that might =head1 BUGS -Please see https://virt-manager.org/page/BugReporting +Please see L =head1 COPYRIGHT