Archived community.zenoss.org | full text search
Skip navigation
5292 Views 13 Replies Latest reply: Jan 16, 2012 3:20 PM by dpetzel RSS
Rank: Brown Belt 260 posts since
Mar 30, 2009
Currently Being Moderated

Dec 22, 2011 9:41 AM

ZenPack Change Discussion

[08-Dec-2011 11:39:37] <Jane_Curry> I know that became an onerous burden on Zenoss but I am a little concerned that some folk will give up rather than donate code

[08-Dec-2011 11:39:58] <Jane_Curry> Perhaps it is an area where the Zenoss Community Alliance could help users????

In rereading this from an old IRC convo, I now get it - that you (Jane) want to have the ZCA help users ease into git / github use. It makes good sense and I like the idea. I was planning on having a sitting session with Ryan Matte and getting him to use git. He made like 4 updates recently and didnt get them on github... I am assuming because he has not had the time to learn this yet (ryan... comment?). If this is occuring to high-level-contributors, I am sure it will occur with one-off contributors.

 

What if the ZCA could offer to help in posting zenpack code where it is the case that the author does not have the time to learn and use git / github? We would not want this to be the default or to be widely advised, but it would be better than us not distributing the word that the code exists (because the person didnt have time to deal with and learn git).

 

Thoughts?

-Nick Yeates

  • jmp242 ZenossMaster 4,060 posts since
    Mar 7, 2007

    Sounds OK to me, though I personally don't know Git, so it'd have to be one of the developers doing it probably.

     

    --

    James Pulver

    ZCA Member

    LEPP Computer Group

    Cornell University

  • jcurry ZenossMaster 1,021 posts since
    Apr 15, 2008

    I think this is a good idea.  I am no git guru but at least my recent updates do seem to have made it.

     

    Anyone have any suggestions how we promote this?  Pointer to the ZCA website to a suitable landing page to request ZCA assistance in publishing ZenPacks?

     

    Nick - the presentation that you did to the ZCA recently to educate us about git - could that be made available to us?

     

    Cheers,

    Jane

  • dpetzel Rank: Brown Belt 1,141 posts since
    Oct 17, 2010

    My .02:

     

    Zenoss Inc. should provide a "template" README.rst file (ideally created on ZenPack creation). The reality is that people are going to do what they personally think looks best to them, however if a template is available its likely to get used as the starting point.

     

    As to the screen shot question. My preference is no screen shots up front, but keep them at the end. For me having informative text up front is more useful than images. Again just a personal preference though. I like having the screen shots at the end of the document with a TOC upfront. IE docs/DOC-12963. If someone wants the screenshots first/only then the TOC provides a quick link to the bottom of the document directly to the screen shots.

  • jcurry ZenossMaster 1,021 posts since
    Apr 15, 2008

    Totally support an unignorable README.rst template.  I don't have strong feelings about where the screenshots go it's a personal thing.

     

    This mechanism should also include where you put your screenshots - I have created a screenshots directory under my base ZenPack.  It's all about making this process as easy as possible for folks who, typically, are not fundamentally developers.

     

    Thanks also, dpetzel, for your earlier input on uploading egg files - another element of ZenPack publishing which needs incorporating into Nick's document and standardising ( docs/DOC-8495#comment-4950 .  Does anyone have further comments on my last post in this entry which I reproduce here??

     

    ----

     

    Why are there two different URLs to a downloads area and which should we use???

     

    You [Nick] quote https://github.com/downloads/jcurry/ZenPacks.skills1st.MenuExamples/ZenPacks.skills1st.MenuExamples-1.0-py2.6.egg which does work provided you type it all in - note the dowloads before the name in the URL - but this doesn't satisfy the sensible comment from dpetzel about having access to a variety of downloads.  To get there, you need a URL like https://github.com/jcurry/ZenPacks.skills1st.MenuExamples/downloads where presumably you can have multiple files for download.

     

    -----

     

    Cheers,

    Jane

  • dpetzel Rank: Brown Belt 1,141 posts since
    Oct 17, 2010

    So Zenoss will be doing an automatted install test each day of each pack? I like that idea. I also like the idea of the egg getting uploaded automatically, HOWEVER, it doesnt really address the issue of making the process less complex. It removes a step or two from the complex process, but what about an SA that hacks up a template without any code and wants to share?

     

    If I have a ZenPack which contains 0 code, I shouldn't need to setup a github account and learn how to use GIT. I'm all for the automatted process on packs that include custom code, but I think it addresses a very small sliver of the larger issue around being able to contribute.

     

    On a related note, IF the GitHub auto-build is THE process, is there any reason we can't automate the Jump Pages? Since github supports commit hooks to readthedocs, and your using a submodules to each pack, a centeral ReST index and proper sphinx configuration could allow automating building of Jump Pages (albeit it woud live outside of Jive)

  • Chet Luther ZenossEmployee 1,302 posts since
    May 22, 2007

    I'll throw my two cents into each one of these topics. I don't have strong opinions on most of them, but I would like to see them brought to resolution.

     

    Gaudy README.rst Template

    It seems like the desire to create a template README.rst that screams out to be replaced is unanimous. I'm on board with that. Would anyone care to send me what they want to see? I'll get it into the ZenPackTemplate GitHub repository and into the mainline product so it gets automatically created for new ZenPacks when 4.2 is release.

     

    Location of Screenshots

    I prefer that the screenshots be kept in the code repository in the top-level directory. I haven't been particularly consistent in how I've done this with my ZenPacks to date. I second Jane's suggestion of creating a screenshots/ directory in the top-level.

     

    As for where they go in the README.rst? I don't care, and I can see how some would prefer to highlight them at the beginning, intersperse them in context, or stick them at the bottom. I've tended towards the bottom myself because I like the information up front. I say leave it up to the author.

     

    What to do about Eggs?

    As Nick said, I'm in the process of building a system that will automatically build ZenPack eggs for all recent ZenPack versions anytime the repository is updated. I'm pretty excited about this because it's a pain in the neck to build all of the versions of ZenPack that people might need. You need a py2.6 version for Zenoss 3 and you'll need a py2.7 version for Zenoss 4.2 when it's released. If your ZenPack includes compiled code you'll need each one for i386 and x86_64 too.

     

    For the immediate future we can use the GitHub "Downloads" area for packaged eggs. Once the auto-built archive is available, we can transition over to that as long as no one identifies a reason not to.

     

    Automatically Building Documentation

    dpetzel's idea of using Sphinx directly or readthedocs.org is a great one. I'm already using readthedocs.org for docs.zenosslabs.com and it has been a wonderful experience. It would be a minimal enhancement to build system to generate documentation in a variety of formats.

  • dpetzel Rank: Brown Belt 1,141 posts since
    Oct 17, 2010

    Regarding Automated Doc Building:

    1) I would consider this a lose of current functionality (unless some sort of iframe approach is used)

    2) No new Logon. Since we are talking about a read-only view of the DOCS, the source of the docs is GITHUB. At a high level a postcommit hook would simply fire off an automatic rebuild of the docs. This way each time a commit is performed DOCS are rebuilt. No Copying/Pasting from the required README.rst to JIVE.

    3) I'd consider the conversion automatic (to an extent). If the development process is REQURING a README.rst, and the docs are auto-built. I think the conversion process might be as simple as updating current page to say "New Page is over here" and ensure the pack has valid RST file, or simply update the pages that have RST docs to use the proposed iFrame approach.

    4) iFrames have the potential to bridge the Gap between old and new. I can't say I can exactly visualize how auto-build docs would look/feel in the iframe, but at  high level it feels like it could work. 

    5) I believe I've seen docs from "Zenoss API" already so I think the JIVE API has already been figured out by Zenoss. I think the concerns around the API complexity can very likely be overcome.

     

    I honestly feel this auto-doc building might be a premature discussion until the overall contribution process is hashed out (I should have started a seperate thread about it). I think THIS thread has deviated away from the original intention of making the process "less complex" and it only really applies to ZenPacks which are levarging GitHUB and RST. At this point thats a minority and potentially could stay that way for quite some time.

More Like This

  • Retrieving data ...

Legend

  • Correct Answers - 4 points
  • Helpful Answers - 2 points