Dec 22, 2011 9:41 AM
ZenPack Change Discussion
-
Like (0)
[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
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
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
1)
Jane, the git presentation for ZCA is posted!
Zenoss Dev Screencast: ZenPack HowTo 3 part screencast (8, 5 and 7 minutes)
ZenPack Development Process guide links to the above
These two links are the best way to figure this out for newbies.
2)
Announce the git help subtly or maybe just when people come at us in chat or email. I will forward anyone who sends code not in git, to the above links and ZCA if needed. I am also willing to do some hand holding to get them using git.
We want people to jump onto git as much as possible, so really try to stear them that way. If someone that normally was not on github gets on because of a small zenpack, they might also discover in the future that they can help with other code and projects at Zenoss or abroad.
-Nick Yeates-
Community Support Engineer
Zenoss Inc.
Links didnt come up on last one. I reposted reply with links to screencasts.
I am going to hijack this topic.
Chets ZenPack Docs Definition
These define how README.rst's should be constructed:
http://docs.zenosslabs.com/en/latest/zenpack_documentation.html
I am going to update some of it to go along with some of the standardizations that dpetzel and I have been using (or we may need to conform to chets recommendations - Im not sure yet). I know Chet was looking for feedback.
Screenshots
I want some input from others on where we should be placing screenshots in the README.rst's. On jump pages, I had been putting 1-2 nice looking screenshots right after the description of the ZenPack, so that users browsing ZenPacks could visually see its effects. Is a screenshot needed when first checking out a ZenPack? Think from the perspective of both beginner and advanced users - both people browsing and those searching for a specific usage.
Do screenshots still go best at the end - for simplificiations sake? or do we do one screen at the begining and the rest at the end? Or do we not care, and leave it up to each author?
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.
I love these insights and ideas dpetzel. I am fwd'ing to Chet.
Also, we should be careful what goes into this template, so as not to make it easily ignorable. We could make the template have large text at the top saying: "!! UPDATE THIS DOC !!\nThis file should contain documentation that is specific to what your ZenPack does. Currently it only contains an example template of what we suggest."
I suggest this because:
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
Jane,
I will push for unignorable README.rst
I talked to Chet about egg locations - he is working on QA automation (CI continuous integration). Because his CI is going to run within a self-hosted cloud environment (internally @ zenoss, with nice output results to users), and because he will eggify and install and test every ZenPack from code everyday, there is likely to be an automated location to expect to find .egg's on our end. This would take away the need for devs and ZP submitters to upload anything. It would also mean that the URL would not work until our automation scripts catalogue and run on it - maybe a day if no issues. Possibly less. How do you guys like this solution over users upping to github?
I will be interested to see what Chet says on this.
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)
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.
I think we are agreed on most topics. Chets summary captures it well. Some clarifications:
Gaudy README.rst
Ex: https://github.com/zenoss/ZenPacks.ShaneScott.CPUCount/blob/master/README.markdown
Chet, this is in markdown, our original choice, but obviously should be in .rst . It gives a good template / idea on what to use. Feel free to take and modify to your hearts content. Id submit it to the git repo myself if I wasnt on vacation :-)
Screenshots
Place at bottom of jump pages by example, with link to section (TOC) at top. Image files go in /repoName/screenshots . This seems to be the consensus, and we want to set rigorous standards. If people stray out of it, no biggie, we dont enforce it, but at least there is something advised and used in examples.
Automated Doc Building
I do not quite grasp this. We would be implementing zenpack docs similar to a the docs at http://docs.zenosslabs.com/ ? It would be a seperate-from jive site as dpetzel said.... Correct me if wrong. If this is right, some questions:
Anyone feel free to follow up or discuss any of the above.
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.
Follow Us On Twitter »
|
Latest from the Zenoss Blog » | Community | Products | Services Resources | Customers Partners | About Us | ||
Copyright © 2005-2011 Zenoss, Inc.
|
||||||||