[libvirt] docs: Change or update the hacking page
Hi everyone, sorry about the empty message above, I was typing and I pressed the wrong set of keys. So, I was going through the contributor guidelines page[1], and after discussing with Michal Privoznik, I think there are some things that need to be updated. For instance, the 4th point about posting patches mentions using git diff instead of git format-patch. I also feel that the workflow in general should be re-written and updated with some more details. I have written a very detailed post about the workflow here[2], and might pick some points up from there. Please let me know what you think of it. Also, please post the other things that you think should be changed on that page in this thread. Thanks, Nishith [1]: http://libvirt.org/hacking.html [2]: https://nishithshah2211.github.io/git/libvirt/libvirt-git-workflow/ On Wed, May 11, 2016 at 11:30 AM, Nishith Shah <nishithshah.2211@gmail.com> wrote:
On 11.05.2016 08:04, Nishith Shah wrote:
Hi everyone, sorry about the empty message above, I was typing and I pressed the wrong set of keys.
So, I was going through the contributor guidelines page[1], and after discussing with Michal Privoznik, I think there are some things that need to be updated. For instance, the 4th point about posting patches mentions using git diff instead of git format-patch.
Worse, it even suggests using plain diff in which case rename feature will not be effective, originally ignored files would be formatted into the patch too and so on. We definitely need an update that would advice using nothing but git.
I also feel that the workflow in general should be re-written and updated with some more details. I have written a very detailed post about the workflow here[2], and might pick some points up from there. Please let me know what you think of it.
Yes, I think we should update our page. Moreover, I feel like http://libvirt.org/api_extension.html is outdated too. Probably worth it. Michal
On 05/11/2016 02:04 AM, Nishith Shah wrote:
Hi everyone, sorry about the empty message above, I was typing and I pressed the wrong set of keys.
So, I was going through the contributor guidelines page[1], and after discussing with Michal Privoznik, I think there are some things that need to be updated. For instance, the 4th point about posting patches mentions using git diff instead of git format-patch. I also feel that the workflow in general should be re-written and updated with some more details. I have written a very detailed post about the workflow here[2], and might pick some points up from there. Please let me know what you think of it.
Also, please post the other things that you think should be changed on that page in this thread.
I've thought a bit about this too. I don't think the HACKING page is a good landing page for new contributors. It _is_ useful document _everything_ that a contributor might want to know, but I think we should also have a page specifically for a contributor quickstart which has very bare minimum info. I'm not saying this is anything you need to handle :) Just figured I'd throw my thoughts out. Ideas for the hypothetical doc, which shouldn't be more than a page or two: - building libvirt, with links to more complete docs. though one of the hardest bits about getting involved with any project is learning the correct build incantation to make things work. I usually suggest grabbing the ./configure line from rpm --eval '%configure', but libvirt has autogen.sh --system as well, but I haven't tested it in a while - running libvirt: running libvirtd/virsh from git, maybe RPM? probably discouraging 'make install' unless people know what they are doing - basic steps for running make check and make syntax-check - mention that we use git format-patch/send-email, but no instructions, link them if necessary. maybe link to example mailing list postings for guidelines for formatting commit messages/series - A link to the BiteSizedTasks page - Cole
On 11.05.2016 16:01, Cole Robinson wrote:
On 05/11/2016 02:04 AM, Nishith Shah wrote:
Hi everyone, sorry about the empty message above, I was typing and I pressed the wrong set of keys.
So, I was going through the contributor guidelines page[1], and after discussing with Michal Privoznik, I think there are some things that need to be updated. For instance, the 4th point about posting patches mentions using git diff instead of git format-patch. I also feel that the workflow in general should be re-written and updated with some more details. I have written a very detailed post about the workflow here[2], and might pick some points up from there. Please let me know what you think of it.
Also, please post the other things that you think should be changed on that page in this thread.
I've thought a bit about this too. I don't think the HACKING page is a good landing page for new contributors. It _is_ useful document _everything_ that a contributor might want to know, but I think we should also have a page specifically for a contributor quickstart which has very bare minimum info. I'm not saying this is anything you need to handle :) Just figured I'd throw my thoughts out.
Agreed. Good idea!
Ideas for the hypothetical doc, which shouldn't be more than a page or two:
- building libvirt, with links to more complete docs. though one of the hardest bits about getting involved with any project is learning the correct build incantation to make things work. I usually suggest grabbing the ./configure line from rpm --eval '%configure', but libvirt has autogen.sh --system as well, but I haven't tested it in a while
I'd advice them to use the autogen.sh script, because I guess that rpm produces this long command line enabling all the features supported (for instance systemd API requiring systemd-devel and so on). In general, when configure is run without any additional arguments, it enables all the features that it is able to with packages currently installed in the system. I don't think we should require newbies to install sheepdog for instance.
- running libvirt: running libvirtd/virsh from git, maybe RPM? probably discouraging 'make install' unless people know what they are doing
Correct. ./run daemon/libvirtd or ./run tools/virsh. I wouldn't mention RPM as it would replace libvirtd they have in the system, which is a stable one with their buggy one. They are new to the project, there definitely gonna be some bugs in their code.
- basic steps for running make check and make syntax-check
This should be the default. Correct. I usually join them: make all syntax-check check.
- mention that we use git format-patch/send-email, but no instructions, link them if necessary. maybe link to example mailing list postings for guidelines for formatting commit messages/series
Correct.
- A link to the BiteSizedTasks page
Correct. Michal
On Wed, May 11, 2016 at 7:51 PM, Michal Privoznik <mprivozn@redhat.com> wrote:
I've thought a bit about this too. I don't think the HACKING page is a good landing page for new contributors. It _is_ useful document _everything_
contributor might want to know, but I think we should also have a page specifically for a contributor quickstart which has very bare minimum info. I'm not saying this is anything you need to handle :) Just figured I'd
On 11.05.2016 16:01, Cole Robinson wrote: that a throw
my thoughts out.
Agreed. Good idea!
Ideas for the hypothetical doc, which shouldn't be more than a page or
two:
- building libvirt, with links to more complete docs. though one of the hardest bits about getting involved with any project is learning the
correct
build incantation to make things work. I usually suggest grabbing the ./configure line from rpm --eval '%configure', but libvirt has autogen.sh --system as well, but I haven't tested it in a while
I'd advice them to use the autogen.sh script, because I guess that rpm produces this long command line enabling all the features supported (for instance systemd API requiring systemd-devel and so on). In general, when configure is run without any additional arguments, it enables all the features that it is able to with packages currently installed in the system. I don't think we should require newbies to install sheepdog for instance.
- running libvirt: running libvirtd/virsh from git, maybe RPM? probably discouraging 'make install' unless people know what they are doing
Correct. ./run daemon/libvirtd or ./run tools/virsh. I wouldn't mention RPM as it would replace libvirtd they have in the system, which is a stable one with their buggy one. They are new to the project, there definitely gonna be some bugs in their code.
- basic steps for running make check and make syntax-check
This should be the default. Correct. I usually join them: make all syntax-check check.
- mention that we use git format-patch/send-email, but no instructions,
link
them if necessary. maybe link to example mailing list postings for guidelines for formatting commit messages/series
Correct.
- A link to the BiteSizedTasks page
Correct.
I am definitely +1 for this. Having recently gotten my first patch accepted, I would say that a contributor quickstart page which describes how to set up the bare essentials to start contributing with links to more info is a good idea. Also, anything more about changing stuff on the hacking page, like the example I had given about removing the point that mentions using plain diff or git diff? Any more points or things that should be removed, added or updated from that page? Nishith
On 05/11/2016 12:22 PM, Nishith Shah wrote:
On Wed, May 11, 2016 at 7:51 PM, Michal Privoznik <mprivozn@redhat.com> wrote:
I've thought a bit about this too. I don't think the HACKING page is a good landing page for new contributors. It _is_ useful document _everything_
contributor might want to know, but I think we should also have a page specifically for a contributor quickstart which has very bare minimum info. I'm not saying this is anything you need to handle :) Just figured I'd
On 11.05.2016 16:01, Cole Robinson wrote: that a throw
my thoughts out.
Agreed. Good idea!
Ideas for the hypothetical doc, which shouldn't be more than a page or
two:
- building libvirt, with links to more complete docs. though one of the hardest bits about getting involved with any project is learning the
correct
build incantation to make things work. I usually suggest grabbing the ./configure line from rpm --eval '%configure', but libvirt has autogen.sh --system as well, but I haven't tested it in a while
I'd advice them to use the autogen.sh script, because I guess that rpm produces this long command line enabling all the features supported (for instance systemd API requiring systemd-devel and so on). In general, when configure is run without any additional arguments, it enables all the features that it is able to with packages currently installed in the system. I don't think we should require newbies to install sheepdog for instance.
- running libvirt: running libvirtd/virsh from git, maybe RPM? probably discouraging 'make install' unless people know what they are doing
Correct. ./run daemon/libvirtd or ./run tools/virsh. I wouldn't mention RPM as it would replace libvirtd they have in the system, which is a stable one with their buggy one. They are new to the project, there definitely gonna be some bugs in their code.
- basic steps for running make check and make syntax-check
This should be the default. Correct. I usually join them: make all syntax-check check.
- mention that we use git format-patch/send-email, but no instructions,
link
them if necessary. maybe link to example mailing list postings for guidelines for formatting commit messages/series
Correct.
- A link to the BiteSizedTasks page
Correct.
I am definitely +1 for this. Having recently gotten my first patch accepted, I would say that a contributor quickstart page which describes how to set up the bare essentials to start contributing with links to more info is a good idea.
Also, anything more about changing stuff on the hacking page, like the example I had given about removing the point that mentions using plain diff or git diff? Any more points or things that should be removed, added or updated from that page?
Nishith
A link to whatever new is created and perhaps the more detailed hacking from the "first" page (index.html) would be nice! Every time I go looking for the hacking page - it's a memory test to find it... Option 1. documentation -> internals -> hacking.html Option 2. documentation -> architecture -> API concepts (at the bottom of the page) -> hacking.html Option 3. bug reports -> know to click "contributor guidelines" -> hacking.html Option 4. Sitemap -> Contributor guidelines -> hacking.html So on index.html, maybe some sort of "getting started section" after "libvirt provides" that would link directly to the API, how to run, the first time contributor, the hacker... IOW: Direct links to what you may need the more advanced you get. See what happens when you open a can of penguins ;-)... John
On Wed, 2016-05-11 at 10:01 -0400, Cole Robinson wrote:
On 05/11/2016 02:04 AM, Nishith Shah wrote:
Hi everyone, sorry about the empty message above, I was typing and I pressed the wrong set of keys.
So, I was going through the contributor guidelines page[1], and after discussing with Michal Privoznik, I think there are some things that need to be updated. For instance, the 4th point about posting patches mentions using git diff instead of git format-patch. I also feel that the workflow in general should be re-written and updated with some more details. I have written a very detailed post about the workflow here[2], and might pick some points up from there. Please let me know what you think of it.
Also, please post the other things that you think should be changed on that page in this thread.
I've thought a bit about this too. I don't think the HACKING page is a good landing page for new contributors. It _is_ useful document _everything_ that a contributor might want to know, but I think we should also have a page specifically for a contributor quickstart which has very bare minimum info.
We have something like that - it's called README-hacking :) I argued before that HACKING should be our quickstart document, just as is the case with many other projects, and the full contributors guidelines should live in a separate document that bears a different name. -- Andrea Bolognani Software Engineer - Virtualization Team
On Thu, May 12, 2016 at 10:35:54AM +0200, Andrea Bolognani wrote:
On Wed, 2016-05-11 at 10:01 -0400, Cole Robinson wrote:
On 05/11/2016 02:04 AM, Nishith Shah wrote:
Hi everyone, sorry about the empty message above, I was typing and I pressed the wrong set of keys.
So, I was going through the contributor guidelines page[1], and after discussing with Michal Privoznik, I think there are some things that need to be updated. For instance, the 4th point about posting patches mentions using git diff instead of git format-patch. I also feel that the workflow in general should be re-written and updated with some more details. I have written a very detailed post about the workflow here[2], and might pick some points up from there. Please let me know what you think of it.
Also, please post the other things that you think should be changed on that page in this thread.
I've thought a bit about this too. I don't think the HACKING page is a good landing page for new contributors. It _is_ useful document _everything_ that a contributor might want to know, but I think we should also have a page specifically for a contributor quickstart which has very bare minimum info.
We have something like that - it's called README-hacking :)
I argued before that HACKING should be our quickstart document, just as is the case with many other projects, and the full contributors guidelines should live in a separate document that bears a different name.
I'd agree with that - basically stop auto-generating HACKING file from docs/hacking.html.in and move README-hacking to HACKING and have it point to the website for full details. Regards, Daniel -- |: http://berrange.com -o- http://www.flickr.com/photos/dberrange/ :| |: http://libvirt.org -o- http://virt-manager.org :| |: http://autobuild.org -o- http://search.cpan.org/~danberr/ :| |: http://entangle-photo.org -o- http://live.gnome.org/gtk-vnc :|
participants (6)
-
Andrea Bolognani -
Cole Robinson -
Daniel P. Berrange -
John Ferlan -
Michal Privoznik -
Nishith Shah