Re: Feedback from downstreams presentation from DX hackfest 2015
On Tue, 2015-02-10 at 16:11 +, Philip Withnall wrote: Problems building SQL and SPARQL queries • https://bugzilla.gnome.org/show_bug.cgi?id=741777 • SQLite: can’t think of a decent way of fixing this libgda has the GdaSQLBuilder API. It's a bit odd, but it works, and handles different SQL dialects: https://developer.gnome.org/libgda/stable/GdaSqlBuilder.html#GdaSqlBuilder.description I think it's a bit nicer in the (my) C++ wrapper, though it's documentation there is a bare minimum: https://developer.gnome.org/libgdamm/unstable/classGnome_1_1Gda_1_1SqlBuilder.html#details I use the C++ version lots in Glom. At the least, it's a big help to avoid SQL injection that can creep in when you just concatenate strings. I would never use any database API without using some abstraction layer such as libgda. They are all far too strange. I'd rather port one day from one sane abstraction layer to another sane abstraction layer than from some gnarly specific database API to one that's just gnarly in another way. -- Murray Cumming murr...@murrayc.com www.murrayc.com signature.asc Description: This is a digitally signed message part ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: Feedback from downstreams presentation from DX hackfest 2015
On Mon, 2015-02-02 at 12:19 +0100, Olav Vitters wrote: On Mon, Feb 02, 2015 at 08:05:00AM +, Philip Withnall wrote: It was suggested that I send the presentation to DDL, since it might be of general interest. I haven’t modified it from the hackfest version, so please let me know if you have any questions. Can we assume that most still needs to be actioned? Also interested what discussions there were during the hackfest to improving this. E.g. Should we maybe reach out to our advisory board? Some things mentioned lack of documentation. So with DX hackfest and documentation at same time I also wonder if there were any possibilities to improve this. Here’s my list of what has been done for each point, and what still needs doing. Apologies for the messy list, but since a lot of points have been filed as bugs already, there seems little point in writing them up nicely. They should roughly correspond to the points in the presentation, with duplicates removed. If anything’s unclear, please ask! The ‘TODO’ items I still need to follow up on, but there are some open questions next to them (and a few other points). I’ll bring some of those up on DDL in the near future, but any ideas people have about fixing them are welcome any time. SVGs in GtkImages don’t scale with the widget • https://bugzilla.gnome.org/show_bug.cgi?id=728476 Some properties are confusing, such as GtkCellRendererText:editable[-set] • https://bugzilla.gnome.org/show_bug.cgi?id=744052 Document GtkBuilder behaving like a factory • https://bugzilla.gnome.org/show_bug.cgi?id=744053 gtkmm documentation search in Devhelp • https://bugzilla.gnome.org/show_bug.cgi?id=743918 Documentation of widget event masks and event propagation is opaque • https://bugzilla.gnome.org/show_bug.cgi?id=744054 Deprecations should be documented with a rationale and replacement API, and hopefully also a porting guide • https://bugzilla.gnome.org/show_bug.cgi?id=744055 • https://bugzilla.gnome.org/show_bug.cgi?id=744057 Project bootstrapping • To be done in Builder Bootstrapping problems with gettext, intltool, gtk-doc • To be done in Builder Indicating licencing in files • Tartan bug 844/3c7 Knowing which files to put in git • To be done in Builder Parallel installability of libraries • https://bugzilla.gnome.org/show_bug.cgi?id=376123 • TODO: See if any other documentation/examples needs updating Total confusion over LT versioning • Not sure there’s anything which can be done about this — ideas? Namespacing confusion for GObject • (random assortment of related bugs which I will try and go through) • https://bugzilla.gnome.org/show_bug.cgi?id=742587 • https://bugzilla.gnome.org/show_bug.cgi?id=658766 • https://bugzilla.gnome.org/show_bug.cgi?id=705056 • https://bugzilla.gnome.org/show_bug.cgi?id=731997 Encapsulation of members in GObject private structs • https://bugzilla.gnome.org/show_bug.cgi?id=744060 • TODO: Write a HowDoI on subclassing? Repeated, inefficient use of GList • https://bugzilla.gnome.org/show_bug.cgi?id=741024 • https://bugzilla.gnome.org/show_bug.cgi?id=741779 • TODO: Can we do more? Stop promoting linked lists somehow? Confusion between sync, async and threads • https://bugzilla.gnome.org/show_bug.cgi?id=741779 • https://mail.gnome.org/archives/desktop-devel-list/2015-February/msg00038.html - Static analysis - Dynamic checking (warn if sync functions called in the main loop) - Documentation: hide sync functions unless explicitly asked for; maybe only show async functions in index, add link from them to sync functions to show that documentation - Documentation for best practices for structuring async calls? Massive over-use of g_strdup() • https://bugzilla.gnome.org/show_bug.cgi?id=622721 Persistent confusion over g_free(NULL) • https://bugzilla.gnome.org/show_bug.cgi?id=741779 No compiler, GIR or gtk-doc warnings enabled • https://wiki.gnome.org/Projects/GnomeCommon/Migration • https://wiki.gnome.org/Initiatives/GnomeGoals/ModernAutotools • http://www.gnu.org/software/autoconf-archive/ax_compiler_flags.html No gtk-doc tests enabled • https://git.gnome.org/browse/gtk-doc/commit/?id=034942538432979f51e74 Confusion over documentation generation with gdbus-codegen • https://bugzilla.gnome.org/show_bug.cgi?id=743294 Tests were not automatable • For example, some tests in the wild ask for user input, and print output rather than asserting it’s some known, expected value. The user is expected to check the output manually. • Not sure if there’s anything which can be done upstream to discourage this. Tests were not hooked up to CI or other tooling • TODO: Somehow make GTest easier to hook up to CI? TAP support is a good step. What else can be done? APIs were untestable by design • This arises from use of global resources, such as databases in the home directory, or system services, by code under test. The fix is to structure the code to allow those resources to
Re: Feedback from downstreams presentation from DX hackfest 2015
On Tue, Feb 3, 2015 at 3:52 AM, Ryan Lortie de...@desrt.ca wrote: hi, On Mon, Feb 2, 2015, at 10:10, Michael Catanzaro wrote: FWIW, if you run devhelp with jhbuild, you will get documentation for the version of the library in jhbuild. This is only true if the docs are actually built, which is not the case by default (and, unless we dramatically improve performance, shouldn't be). Cheers Oh yeah good point, I was only building them for work on a bug. And they are really slow, we should keep them disabled. ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: Feedback from downstreams presentation from DX hackfest 2015
On Mon, 2015-02-02 at 08:05 +, Philip Withnall wrote: [snip] Handout: http://people.collabora.com/~pwith/feedback-from-downstreams/handout.pdf That mentions this: Gtkmm's documentation is poor in comparison to GTK+'s and it works really badly in Devhelp. Searching (an important feature we take for granted when using the C API) is especially bad Searching of gtkmm documentation has been working in devhelp for years, and I've just tested it here both in regular Ubuntu and in jhbuild. I mean, searching of the index, of course. I don't think devhelp offers full text search for any documentation. If there's any particular problem, or if I've misunderstood, we'd like to hear about it. As for the rest of the documentation, I don't feel it's that bad apart from a few holes here and there. In many places it's vastly clearer because we've had to figure out how the (often poorly documented) GTK+ APIs are meant to be used. Our gtkmm book is now very out of date because we've haven't updated it for the many API additions and deprecations over the last 3 years or so. When it was up to date people seemed very happy with it. I can't devote enough of my free time anymore to updating it fully but I'm available for freelance work. -- Murray Cumming murr...@murrayc.com www.murrayc.com ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: Feedback from downstreams presentation from DX hackfest 2015
On Mon, 2015-02-02 at 16:51 +, Philip Withnall wrote: Documentation is generated from C comments as at the moment, reformatted, uploaded to developer.gnome.org, and then some kind of online interface can be used to edit the documentation (and possibly add comments to it) with instant gratification. That’s what the first few points are about. There are no requirements covering how these online edits would be fed back into the C comments, but presumably that would happen somehow. The fact that there are no requirements means nobody in the hackfest discussion had strong feelings about how it should be done. A long time ago, Danilo Segan kind of had this working at least for DocBook as a Google Summer of Code project: https://wiki.gnome.org/Attic/LiveDocumentationEditing -- Murray Cumming murr...@murrayc.com www.murrayc.com signature.asc Description: This is a digitally signed message part ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: Feedback from downstreams presentation from DX hackfest 2015
On Mon, 2015-02-02 at 16:31 +0100, Olav Vitters wrote: On Mon, Feb 02, 2015 at 02:37:32PM +, Philip Withnall wrote: What do you mean by reaching out to the advisory board? Reaching out for further feedback from them as downstreams, or reaching out for resources to fix such issues? I think the former would be interesting. I’m not sure the latter is worth their time, since it’s a very loosely defined goal. I meant for resources. Though we should have a team to continuously reach out, find out issues and act on them. If we don't act/respond (which could be about going back and saying we cannot change it), then no point in asking. Agreed, there is no point in asking if we can’t follow up. Other than that, I don’t really have an opinion about asking the advisory board. 4. Instant gratification: documentation changes should be visible instantly, rather than waiting 6 months for a GNOME release before the docs hit developer.gnome.org. The current infrastructure really requires tarballs. We could reuse continuous integration builds to spit out tarballs to feed to developer.gnome.org. It would not be instant, but you'd cut it down to 15 minutes maybe? It would be a huge improvement. I think 15 minutes is still long enough for someone writing docs to lose interest and start looking at pictures of cats instead. I think we should aim to get it down to the time taken to rebuild the docs, so around 1 minute. If that requires a big change in the current infrastructure, then I guess we need to make a big change in the current infrastructure. Philip signature.asc Description: This is a digitally signed message part ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: Feedback from downstreams presentation from DX hackfest 2015
On Mon, 2015-02-02 at 17:11 +0100, Sébastien Wilmet wrote: On Mon, Feb 02, 2015 at 04:51:32PM +0100, Aleksander Morgado wrote: Devhelp could also have a 'next' or 'latest' default profile which could sync the daily? built documentation from gnome.org. Although not sure how useful this could be if we setup the default jhbuild-based profile. I personally think that the profiles idea could be a good one, also as a first step for the next stuff. What do others think? Having only the 'latest' profile should be sufficient for most developers, for each major version of a library of course (e.g. the latest gtk 2.x and the latest gtk 3.x). Each symbol has the Since: version information anyway. And by having the latest documentations, developers are aware of new features and don't reinvent the wheel or don't use APIs that are already deprecated since a later version. But 'latest' should have two variants: stable and unstable. Of course, having other profiles for specific versions of GNOME would be nice, but the 'latest' profiles should be the default and recommended in my opinion. I believe there are various APIs where the ‘Since’ annotations have not been, and are not, added correctly. I suspect we will have to aim for having profiles for each minor release of each library — but that should not be any more complex than supporting latest stable and latest unstable profiles, which I think is a great idea. One question: does ‘latest unstable’ mean git master, or the latest release in the unstable branch? There are plenty of times I’ve needed documentation for unreleased functions newly added in git master; I can’t think of any time I’ve needed documentation for the latest unstable release instead. Philip signature.asc Description: This is a digitally signed message part ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: Feedback from downstreams presentation from DX hackfest 2015
On Mon, 2015-02-02 at 19:56 -0800, Philip Chimento wrote: On Mon, Feb 2, 2015 at 6:37 AM, Philip Withnall phi...@tecnocode.co.uk wrote: On Mon, 2015-02-02 at 12:19 +0100, Olav Vitters wrote: On Mon, Feb 02, 2015 at 08:05:00AM +, Philip Withnall wrote: It was suggested that I send the presentation to DDL, since it might be of general interest. I haven’t modified it from the hackfest version, so please let me know if you have any questions. Can we assume that most still needs to be actioned? Also interested what discussions there were during the hackfest to improving this. E.g. Should we maybe reach out to our advisory board? Some things mentioned lack of documentation. So with DX hackfest and documentation at same time I also wonder if there were any possibilities to improve this. Some of the items need actioning via bugs, which I will sort out. Some of them have already been fixed (either as part of the client work by Collabora, or by others in the time since). Some of them are unfixable, and can only be used as general guidelines for trying to avoid such problems in future (e.g. in new API designs). Thanks for sharing! One point from the slides was familiar enough to jump out at me, and it's a bit of a strange one because it's not actionable via a bug report nor a matter of API design: New functionality needs documenting: GtkBuilder templates were blogged about extensively, but are given a single sentence in the manual This actually happens quite a lot, in my experience. For someone just starting out, blogs are not very discoverable, and they won't know the blogger by name as maintainer of X. I wonder if we could take this existing enthusiasm for documenting something in a blog post and channel it into the API docs. For example I really like your own occasional series of posts about GObject stuff (e.g. [1]) but it would probably help more people if something like these code examples existed in the API docs. I do get that blog posts are more fun to write because they are informal, and they also build your reputation online whereas API docs are anonymous. Totally agreed, and I’m very guilty of this. :-( The only solution I can think of is for people to comment on such blog posts and gently remind the author to ensure everything’s documented upstream. Matthias did this quite well with one of his GUADEC GTK+ presentations (IIRC [1]) where the presentation was basically just various bits of upstream documentation which he had updated specially. Maybe we could see more of that in future? Philip [1]: http://blogs.gnome.org/mclasen/2014/07/28/a-talk-in-9-images/ signature.asc Description: This is a digitally signed message part ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: Feedback from downstreams presentation from DX hackfest 2015
On Tue, 2015-02-03 at 11:26 +0100, Murray Cumming wrote: On Tue, 2015-02-03 at 09:23 +0100, Murray Cumming wrote: Searching of gtkmm documentation has been working in devhelp for years, and I've just tested it here both in regular Ubuntu and in jhbuild. I mean, searching of the index, of course. I don't think devhelp offers full text search for any documentation. If there's any particular problem, or if I've misunderstood, we'd like to hear about it. Actually, I think I just found a big problem with gtkmm's devhelp index: https://bugzilla.gnome.org/show_bug.cgi?id=743918 It seems to be a doxygen bug - hopefully we can figure out a simple test case. That might explain things! The point I made in the presentation about this contains all the information I know about the problems with gtkmm documentation — someone else was on that project, so all my information is second-hand. I’m getting in touch with them to see if we can clarify what the problem is, and whether it’s the one you’ve just found. Cheers, Philip signature.asc Description: This is a digitally signed message part ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: Feedback from downstreams presentation from DX hackfest 2015
On Tue, 2015-02-03 at 09:23 +0100, Murray Cumming wrote: Searching of gtkmm documentation has been working in devhelp for years, and I've just tested it here both in regular Ubuntu and in jhbuild. I mean, searching of the index, of course. I don't think devhelp offers full text search for any documentation. If there's any particular problem, or if I've misunderstood, we'd like to hear about it. Actually, I think I just found a big problem with gtkmm's devhelp index: https://bugzilla.gnome.org/show_bug.cgi?id=743918 It seems to be a doxygen bug - hopefully we can figure out a simple test case. -- Murray Cumming murr...@murrayc.com www.murrayc.com ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: Feedback from downstreams presentation from DX hackfest 2015
hi, On Mon, Feb 2, 2015, at 10:10, Michael Catanzaro wrote: FWIW, if you run devhelp with jhbuild, you will get documentation for the version of the library in jhbuild. This is only true if the docs are actually built, which is not the case by default (and, unless we dramatically improve performance, shouldn't be). Cheers ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: Feedback from downstreams presentation from DX hackfest 2015
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 On 02/02/2015 05:51 PM, Philip Withnall wrote: On Mon, 2015-02-02 at 07:55 -0800, Jasper St. Pierre wrote: On Feb 2, 2015 6:37 AM, Philip Withnall phi...@tecnocode.co.uk wrote: On Mon, 2015-02-02 at 12:19 +0100, Olav Vitters wrote: On Mon, Feb 02, 2015 at 08:05:00AM +, Philip Withnall wrote: It was suggested that I send the presentation to DDL, since it might be of general interest. I haven’t modified it from the hackfest version, so please let me know if you have any questions. Can we assume that most still needs to be actioned? Also interested what discussions there were during the hackfest to improving this. E.g. Should we maybe reach out to our advisory board? Some things mentioned lack of documentation. So with DX hackfest and documentation at same time I also wonder if there were any possibilities to improve this. Some of the items need actioning via bugs, which I will sort out. Some of them have already been fixed (either as part of the client work by Collabora, or by others in the time since). Some of them are unfixable, and can only be used as general guidelines for trying to avoid such problems in future (e.g. in new API designs). What do you mean by reaching out to the advisory board? Reaching out for further feedback from them as downstreams, or reaching out for resources to fix such issues? I think the former would be interesting. I’m not sure the latter is worth their time, since it’s a very loosely defined goal. There were some DX–documentation discussions, although I wasn’t involved in all of them so I can’t report fully. One interesting discussion came up with a set of requirements for any replacement for gtk-doc: 1. Do not want to write XML in documentation comments. Too painful, and a steep learning curve. 2. No version control program (but wikis’ version control is fine). Too much of a barrier for contribution. 3. No waiting for review of documentation changes — post-hoc gives a much lower barrier to contribution instead. 4. Instant gratification: documentation changes should be visible instantly, rather than waiting 6 months for a GNOME release before the docs hit developer.gnome.org. 5. Documents need to be available offline in Devhelp. 6. Devhelp needs to give you documentation for the version of the library you’re using (e.g. in JHBuild), not the version installed on your system, which is invariably outdated. 7. Automatically generate documentation from annotations as much as possible (e.g. eliminate ‘Free return value with g_free()’ in favour of (transfer full)). 8. Topic-based help which can be reorganised dynamically; eliminate in-order Docbook indexes. Basically the Mallard approach for reference documentation. 9. Don’t put big code examples in C comments; move them to separate C files instead, which can be compiled stand-alone. Have a way of limiting what gets rendered in the docs, plus a link to the full source. 10. Don’t parse C with regexps; use documentation from GIR files, and allow g-ir-scanner to do the C parsing legwork. I'm confused. You want both a wiki, and docs embedded in comments? What are you imagining here? Sorry, I should have explained that more clearly. Documentation is generated from C comments as at the moment, reformatted, uploaded to developer.gnome.org, and then some kind of online interface can be used to edit the documentation (and possibly add comments to it) with instant gratification. That’s what the first few points are about. This was proposed already for GSOC. In a nutshell the idea was that gtk-doc would a markdown editor with extra metadata into the generated html. When editing this would submt patches to bugzilla (as this is our code-review tool). The infrastructure team was against tools submiitting to bugzilla. We could probably also push to special doc-review branches on git. While this sounds all doable, it unfortunately get more complicated. We'd need to show that a doc 'unit' already has pending patches so that new edits won't clash, then engine would need to be able to somehow rebase them one new doc-builds, ... Stefan There are no requirements covering how these online edits would be fed back into the C comments, but presumably that would happen somehow. The fact that there are no requirements means nobody in the hackfest discussion had strong feelings about how it should be done. Philip ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list -BEGIN PGP SIGNATURE- Version: GnuPG v1 iEYEARECAAYFAlTRQ7IACgkQITDA+qr9gcyTdwCfRUKg5Acv7AhtvMlMjNnNDHfE llYAnROqAGAF20ZWp/36dNeFhrl5PanW =yG9M -END PGP SIGNATURE- ___ desktop-devel-list mailing list
Re: Feedback from downstreams presentation from DX hackfest 2015
On Mon, 2015-02-02 at 14:47 +0100, Bastien Nocera wrote: On Mon, 2015-02-02 at 08:05 +, Philip Withnall wrote: At the DX hackfest last week[1] I gave an informal presentation about some of the work Collabora has been doing with GLib, GStreamer, Clutter, GTK+ and related technologies on client projects, specifically focusing on the feedback from two client projects, and the problems we encountered downstream which could motivate upstream development in the future. We discussed various issues around those in the presentation, and have some ideas for fixing some of the problems which we did not manage to fix at the time of doing the work downstream. Some of these problems are inherently unfixable, though, and are mentioned purely to motivate future API designs to direct people towards a single, correct, intended usage of the API, as much as that is possible. It was suggested that I send the presentation to DDL, since it might be of general interest. I haven’t modified it from the hackfest version, so please let me know if you have any questions. I think a lot of the problems in this report need bugs created, so that the information trickles down to the appropriate maintainers. It would also greatly help with tracking of the overall goals of improving our stack. Yup, that’s definitely on my to-do list. It will take an hour or two though, so it might take me a few days to get to. Philip signature.asc Description: This is a digitally signed message part ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: Feedback from downstreams presentation from DX hackfest 2015
On Mon, Feb 02, 2015 at 08:05:00AM +, Philip Withnall wrote: It was suggested that I send the presentation to DDL, since it might be of general interest. I haven’t modified it from the hackfest version, so please let me know if you have any questions. Can we assume that most still needs to be actioned? Also interested what discussions there were during the hackfest to improving this. E.g. Should we maybe reach out to our advisory board? Some things mentioned lack of documentation. So with DX hackfest and documentation at same time I also wonder if there were any possibilities to improve this. Slides: http://people.collabora.com/~pwith/feedback-from-downstreams/presentation.pdf Handout: http://people.collabora.com/~pwith/feedback-from-downstreams/handout.pdf Source: http://cgit.collabora.com/git/user/pwith/feedback-from-downstreams.git/ Tarball: http://people.collabora.com/~pwith/feedback-from-downstreams/source.tar.xz -- Regards, Olav ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: Feedback from downstreams presentation from DX hackfest 2015
On Mon, Feb 2, 2015 at 6:37 AM, Philip Withnall phi...@tecnocode.co.uk wrote: On Mon, 2015-02-02 at 12:19 +0100, Olav Vitters wrote: On Mon, Feb 02, 2015 at 08:05:00AM +, Philip Withnall wrote: It was suggested that I send the presentation to DDL, since it might be of general interest. I haven’t modified it from the hackfest version, so please let me know if you have any questions. Can we assume that most still needs to be actioned? Also interested what discussions there were during the hackfest to improving this. E.g. Should we maybe reach out to our advisory board? Some things mentioned lack of documentation. So with DX hackfest and documentation at same time I also wonder if there were any possibilities to improve this. Some of the items need actioning via bugs, which I will sort out. Some of them have already been fixed (either as part of the client work by Collabora, or by others in the time since). Some of them are unfixable, and can only be used as general guidelines for trying to avoid such problems in future (e.g. in new API designs). Thanks for sharing! One point from the slides was familiar enough to jump out at me, and it's a bit of a strange one because it's not actionable via a bug report nor a matter of API design: New functionality needs documenting: GtkBuilder templates were blogged about extensively, but are given a single sentence in the manual This actually happens quite a lot, in my experience. For someone just starting out, blogs are not very discoverable, and they won't know the blogger by name as maintainer of X. I wonder if we could take this existing enthusiasm for documenting something in a blog post and channel it into the API docs. For example I really like your own occasional series of posts about GObject stuff (e.g. [1]) but it would probably help more people if something like these code examples existed in the API docs. I do get that blog posts are more fun to write because they are informal, and they also build your reputation online whereas API docs are anonymous. [1] https://tecnocode.co.uk/2014/12/19/use-g_set_object-to-simplify-and-safetyify-gobject-property-setters/ Best, -- Philip ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: Feedback from downstreams presentation from DX hackfest 2015
On Mon, Feb 02, 2015 at 02:37:32PM +, Philip Withnall wrote: What do you mean by reaching out to the advisory board? Reaching out for further feedback from them as downstreams, or reaching out for resources to fix such issues? I think the former would be interesting. I’m not sure the latter is worth their time, since it’s a very loosely defined goal. I meant for resources. Though we should have a team to continuously reach out, find out issues and act on them. If we don't act/respond (which could be about going back and saying we cannot change it), then no point in asking. 4. Instant gratification: documentation changes should be visible instantly, rather than waiting 6 months for a GNOME release before the docs hit developer.gnome.org. The current infrastructure really requires tarballs. We could reuse continuous integration builds to spit out tarballs to feed to developer.gnome.org. It would not be instant, but you'd cut it down to 15 minutes maybe? It would be a huge improvement. -- Regards, Olav ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: Feedback from downstreams presentation from DX hackfest 2015
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 Hey, 6. Devhelp needs to give you documentation for the version of the library you’re using (e.g. in JHBuild), not the version installed on your system, which is invariably outdated. Last year I started some work to allow kind of 'profiles' in Devhelp. The basic profile would be the current default behavior of looking for books in the default system paths. Then, users could also create their own profiles, e.g. based on a custom --prefix. Following the same idea, a default jhbuild profile could look for books in jhbuild's default install path. There's a branch in devhelp's git with that work started. 5. Documents need to be available offline in Devhelp. We also had some other ideas, like being able to define profiles for different target gnome versions, and then get the books for that version directly from somewhere in gnome.org. 4. Instant gratification: documentation changes should be visible instantly, rather than waiting 6 months for a GNOME release before the docs hit developer.gnome.org. Devhelp could also have a 'next' or 'latest' default profile which could sync the daily? built documentation from gnome.org. Although not sure how useful this could be if we setup the default jhbuild-based profile. I personally think that the profiles idea could be a good one, also as a first step for the next stuff. What do others think? - -- Aleksander -BEGIN PGP SIGNATURE- Version: GnuPG v2 iEUEARECAAYFAlTPnQAACgkQgxIgkKLogl6KnQCY4uAek7ldUMzkXfdHV7g0bMAz iACgpibW66+iRWZ/5UtUmW4HiRLfv9k= =BBOk -END PGP SIGNATURE- ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: Feedback from downstreams presentation from DX hackfest 2015
On Mon, 2015-02-02 at 07:55 -0800, Jasper St. Pierre wrote: On Feb 2, 2015 6:37 AM, Philip Withnall phi...@tecnocode.co.uk wrote: On Mon, 2015-02-02 at 12:19 +0100, Olav Vitters wrote: On Mon, Feb 02, 2015 at 08:05:00AM +, Philip Withnall wrote: It was suggested that I send the presentation to DDL, since it might be of general interest. I haven’t modified it from the hackfest version, so please let me know if you have any questions. Can we assume that most still needs to be actioned? Also interested what discussions there were during the hackfest to improving this. E.g. Should we maybe reach out to our advisory board? Some things mentioned lack of documentation. So with DX hackfest and documentation at same time I also wonder if there were any possibilities to improve this. Some of the items need actioning via bugs, which I will sort out. Some of them have already been fixed (either as part of the client work by Collabora, or by others in the time since). Some of them are unfixable, and can only be used as general guidelines for trying to avoid such problems in future (e.g. in new API designs). What do you mean by reaching out to the advisory board? Reaching out for further feedback from them as downstreams, or reaching out for resources to fix such issues? I think the former would be interesting. I’m not sure the latter is worth their time, since it’s a very loosely defined goal. There were some DX–documentation discussions, although I wasn’t involved in all of them so I can’t report fully. One interesting discussion came up with a set of requirements for any replacement for gtk-doc: 1. Do not want to write XML in documentation comments. Too painful, and a steep learning curve. 2. No version control program (but wikis’ version control is fine). Too much of a barrier for contribution. 3. No waiting for review of documentation changes — post-hoc gives a much lower barrier to contribution instead. 4. Instant gratification: documentation changes should be visible instantly, rather than waiting 6 months for a GNOME release before the docs hit developer.gnome.org. 5. Documents need to be available offline in Devhelp. 6. Devhelp needs to give you documentation for the version of the library you’re using (e.g. in JHBuild), not the version installed on your system, which is invariably outdated. 7. Automatically generate documentation from annotations as much as possible (e.g. eliminate ‘Free return value with g_free()’ in favour of (transfer full)). 8. Topic-based help which can be reorganised dynamically; eliminate in-order Docbook indexes. Basically the Mallard approach for reference documentation. 9. Don’t put big code examples in C comments; move them to separate C files instead, which can be compiled stand-alone. Have a way of limiting what gets rendered in the docs, plus a link to the full source. 10. Don’t parse C with regexps; use documentation from GIR files, and allow g-ir-scanner to do the C parsing legwork. I'm confused. You want both a wiki, and docs embedded in comments? What are you imagining here? Sorry, I should have explained that more clearly. Documentation is generated from C comments as at the moment, reformatted, uploaded to developer.gnome.org, and then some kind of online interface can be used to edit the documentation (and possibly add comments to it) with instant gratification. That’s what the first few points are about. There are no requirements covering how these online edits would be fed back into the C comments, but presumably that would happen somehow. The fact that there are no requirements means nobody in the hackfest discussion had strong feelings about how it should be done. Philip signature.asc Description: This is a digitally signed message part ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: Feedback from downstreams presentation from DX hackfest 2015
On Mon, Feb 02, 2015 at 04:51:32PM +0100, Aleksander Morgado wrote: Devhelp could also have a 'next' or 'latest' default profile which could sync the daily? built documentation from gnome.org. Although not sure how useful this could be if we setup the default jhbuild-based profile. I personally think that the profiles idea could be a good one, also as a first step for the next stuff. What do others think? Having only the 'latest' profile should be sufficient for most developers, for each major version of a library of course (e.g. the latest gtk 2.x and the latest gtk 3.x). Each symbol has the Since: version information anyway. And by having the latest documentations, developers are aware of new features and don't reinvent the wheel or don't use APIs that are already deprecated since a later version. But 'latest' should have two variants: stable and unstable. Of course, having other profiles for specific versions of GNOME would be nice, but the 'latest' profiles should be the default and recommended in my opinion. Sébastien ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list
Feedback from downstreams presentation from DX hackfest 2015
At the DX hackfest last week[1] I gave an informal presentation about some of the work Collabora has been doing with GLib, GStreamer, Clutter, GTK+ and related technologies on client projects, specifically focusing on the feedback from two client projects, and the problems we encountered downstream which could motivate upstream development in the future. We discussed various issues around those in the presentation, and have some ideas for fixing some of the problems which we did not manage to fix at the time of doing the work downstream. Some of these problems are inherently unfixable, though, and are mentioned purely to motivate future API designs to direct people towards a single, correct, intended usage of the API, as much as that is possible. It was suggested that I send the presentation to DDL, since it might be of general interest. I haven’t modified it from the hackfest version, so please let me know if you have any questions. Slides: http://people.collabora.com/~pwith/feedback-from-downstreams/presentation.pdf Handout: http://people.collabora.com/~pwith/feedback-from-downstreams/handout.pdf Source: http://cgit.collabora.com/git/user/pwith/feedback-from-downstreams.git/ Tarball: http://people.collabora.com/~pwith/feedback-from-downstreams/source.tar.xz Philip signature.asc Description: This is a digitally signed message part ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list
