- Release-team - mailman3.cels.anl.gov

Re: [Release-team] Adding columns to services spreadsheet
by Land, Miriam L. 01 Feb '13

01 Feb '13

A more stable place would be to put it in the Master tab. I copied and pasted from the git repo yesterday but the descriptions were weak. Miriam On 2/1/13 9:39 AM, "Thomas Brettin" <brettin(a)mcs.anl.gov> wrote: >Hi Elizabeth, > >I'm building the list of modules for attempted release next week. I got a >one sentence to paragraph size description of the service from a lot of >the module owners. I'm just pasting those into the kbase services spread >sheet "Feb 4 Major' tab. Take what ever you want. We can reorganize later. > >Tom >On Jan 31, 2013, at 11:49 AM, Elizabeth M. Glass <marland(a)mcs.anl.gov> >wrote: > >> Can we also add in a column on what science domains these services work >>for? M, MC, P >> >> Elizabeth >> >> ----- Original Message ----- >> From: Thomas Brettin <brettin(a)mcs.anl.gov> >> To: Miriam L. Land <landml(a)ornl.gov> >> Cc: release-team(a)lists.kbase.us, Nomi Harris <nlharris(a)lbl.gov> >> Sent: Thu, 31 Jan 2013 07:09:21 -0600 (CST) >> Subject: Re: [Release-team] Adding columns to services spreadsheet >> >> I want to keep all tabs. I plan to mine this data for research on the >>progression of the development of a release infrastructure. >> >> Tom >> >> On Jan 31, 2013, at 7:05 AM, "Land, Miriam L." <landml(a)ornl.gov> wrote: >> >>> I'm in favor of a master tab. It would be very useful when I need to >>>look >>> up something that was somewhere in an earlier build. >>> >>> I also don't have a problem deleting the tabs that came before Nov >>>Build, >>> as long as we capture information on old modules that may come up >>>again. >>> >>> I think the git repo is a great place to start parsing out the >>> descriptions. >>> >>> Until the redeploy happens this morning, I have time to get this >>>started. >>> >>> Miriam >>> >>> On 1/30/13 5:50 PM, "Nomi Harris" <nlharris(a)lbl.gov> wrote: >>> >>>> Right, I don't want to add another doc either! That's why I was >>>>asking if >>>> I could just add these two columns to the Services doc. I think >>>>they'd be >>>> useful to the people who are on the Build teams as well (maybe not so >>>> much to the people on the release team, since we already pretty much >>>>know >>>> the info that will be in those columns). >>>> I'm ok with either adding it to the Feb tab or making a new "master" >>>>tab. >>>> Nomi Harris >>>> Project Manager, KBase >>>> >>>> On Jan 30, 2013, at 1:33 PM, Dan Olson <dolson(a)mcs.anl.gov> wrote: >>>> >>>>> I'm all for adding a "master" tab to the services spreadsheet with >>>>>the >>>>> static information that doesn't change every release. >>>>> >>>>> I really don't want to add another doc - right now we have - >>>>> A punch list doc >>>>> An email template doc >>>>> A trac wiki page >>>>> A services spreadsheet >>>>> >>>>> As time goes on the more info repositories we have the more >>>>>opportunity >>>>> for them >>>>> to diverge and confusion to occur. >>>>> >>>>> ----- Original Message ----- >>>>>> From: "Miriam L. Land" <landml(a)ornl.gov> >>>>>> To: "Nomi Harris" <nlharris(a)lbl.gov>, release-team(a)lists.kbase.us >>>>>> Sent: Wednesday, January 30, 2013 3:25:48 PM >>>>>> Subject: Re: [Release-team] Adding columns to services spreadsheet >>>>>> >>>>>> Would it make sense to put the common name, repo name, contact(s), >>>>>> and >>>>>> description in a doc by itself? It could be cumulative across all >>>>>> releases. >>>>>> >>>>>> Miriam >>>>>> >>>>>> On 1/30/13 3:39 PM, "Nomi Harris" <nlharris(a)lbl.gov> wrote: >>>>>> >>>>>>> Today I talked to Elizabeth, who is starting to work on materials >>>>>>> for the >>>>>>> User Zone on the website, which will include tutorials, a new User >>>>>>> Guide, >>>>>>> and more. She is also helping to write the text about the >>>>>>>individual >>>>>>> services that is currently on >>>>>>> http://www.kbase.us/developer-zone/services/ . >>>>>>> Elizabeth asked me for two pieces of information for each service: >>>>>>> the >>>>>>> git repo name and corresponding "human language" name of each >>>>>>> service >>>>>>> (for example, Central Store Service is in the kb_seed repo--you'd >>>>>>> never >>>>>>> guess that if you didn't already know), and also whether the >>>>>>>service >>>>>>> is >>>>>>> internal-only or user-facing. I think this information would be >>>>>>> useful to >>>>>>> have on the Services spreadsheet (in fact, that spreadsheet used to >>>>>>> have >>>>>>> the human and git repo names for each service, but lost that at >>>>>>>some >>>>>>> point), but it already has a lot of columns, so I'd like permission >>>>>>> to >>>>>>> add those two. >>>>>>> The Feb 4 Major tab >>>>>>> >>>>>>> >>>>>>>(https://docs.google.com/a/lbl.gov/spreadsheet/ccc?key=0Ana5oznWypH2 >>>>>>>dFp >>>>>>> paE >>>>>>> JzOUdfMV8zN0Y3Vm5YM095aWc#gid=14) is empty so far, so maybe we can >>>>>>> start >>>>>>> from scratch and think about what columns make sense. There were >>>>>>> some on >>>>>>> the previous tabs that we probably don't need anymore. >>>>>>> Thanks, >>>>>>> Nomi Harris >>>>>>> Project Manager, KBase >>>>>>> >>>>>>> _______________________________________________ >>>>>>> Release-team mailing list >>>>>>> Release-team(a)lists.kbase.us >>>>>>> https://lists.kbase.us/mailman/listinfo/release-team >>>>>> >>>>>> _______________________________________________ >>>>>> Release-team mailing list >>>>>> Release-team(a)lists.kbase.us >>>>>> https://lists.kbase.us/mailman/listinfo/release-team >>>>>> >>>> >>>> _______________________________________________ >>>> Release-team mailing list >>>> Release-team(a)lists.kbase.us >>>> https://lists.kbase.us/mailman/listinfo/release-team >>> >>> _______________________________________________ >>> Release-team mailing list >>> Release-team(a)lists.kbase.us >>> https://lists.kbase.us/mailman/listinfo/release-team >> >> Thomas Brettin >> 865-603-7760 (cell) >> brettin(a)mcs.anl.gov >> >> >> >> _______________________________________________ >> Release-team mailing list >> Release-team(a)lists.kbase.us >> https://lists.kbase.us/mailman/listinfo/release-team >> > >Thomas Brettin >865-603-7760 (cell) >brettin(a)mcs.anl.gov > > >

1 0

Re: [Release-team] Adding columns to services spreadsheet
by Thomas Brettin 01 Feb '13

01 Feb '13

Hi Elizabeth, I'm building the list of modules for attempted release next week. I got a one sentence to paragraph size description of the service from a lot of the module owners. I'm just pasting those into the kbase services spread sheet "Feb 4 Major' tab. Take what ever you want. We can reorganize later. Tom On Jan 31, 2013, at 11:49 AM, Elizabeth M. Glass <marland(a)mcs.anl.gov> wrote: > Can we also add in a column on what science domains these services work for? M, MC, P > > Elizabeth > > ----- Original Message ----- > From: Thomas Brettin <brettin(a)mcs.anl.gov> > To: Miriam L. Land <landml(a)ornl.gov> > Cc: release-team(a)lists.kbase.us, Nomi Harris <nlharris(a)lbl.gov> > Sent: Thu, 31 Jan 2013 07:09:21 -0600 (CST) > Subject: Re: [Release-team] Adding columns to services spreadsheet > > I want to keep all tabs. I plan to mine this data for research on the progression of the development of a release infrastructure. > > Tom > > On Jan 31, 2013, at 7:05 AM, "Land, Miriam L." <landml(a)ornl.gov> wrote: > >> I'm in favor of a master tab. It would be very useful when I need to look >> up something that was somewhere in an earlier build. >> >> I also don't have a problem deleting the tabs that came before Nov Build, >> as long as we capture information on old modules that may come up again. >> >> I think the git repo is a great place to start parsing out the >> descriptions. >> >> Until the redeploy happens this morning, I have time to get this started. >> >> Miriam >> >> On 1/30/13 5:50 PM, "Nomi Harris" <nlharris(a)lbl.gov> wrote: >> >>> Right, I don't want to add another doc either! That's why I was asking if >>> I could just add these two columns to the Services doc. I think they'd be >>> useful to the people who are on the Build teams as well (maybe not so >>> much to the people on the release team, since we already pretty much know >>> the info that will be in those columns). >>> I'm ok with either adding it to the Feb tab or making a new "master" tab. >>> Nomi Harris >>> Project Manager, KBase >>> >>> On Jan 30, 2013, at 1:33 PM, Dan Olson <dolson(a)mcs.anl.gov> wrote: >>> >>>> I'm all for adding a "master" tab to the services spreadsheet with the >>>> static information that doesn't change every release. >>>> >>>> I really don't want to add another doc - right now we have - >>>> A punch list doc >>>> An email template doc >>>> A trac wiki page >>>> A services spreadsheet >>>> >>>> As time goes on the more info repositories we have the more opportunity >>>> for them >>>> to diverge and confusion to occur. >>>> >>>> ----- Original Message ----- >>>>> From: "Miriam L. Land" <landml(a)ornl.gov> >>>>> To: "Nomi Harris" <nlharris(a)lbl.gov>, release-team(a)lists.kbase.us >>>>> Sent: Wednesday, January 30, 2013 3:25:48 PM >>>>> Subject: Re: [Release-team] Adding columns to services spreadsheet >>>>> >>>>> Would it make sense to put the common name, repo name, contact(s), >>>>> and >>>>> description in a doc by itself? It could be cumulative across all >>>>> releases. >>>>> >>>>> Miriam >>>>> >>>>> On 1/30/13 3:39 PM, "Nomi Harris" <nlharris(a)lbl.gov> wrote: >>>>> >>>>>> Today I talked to Elizabeth, who is starting to work on materials >>>>>> for the >>>>>> User Zone on the website, which will include tutorials, a new User >>>>>> Guide, >>>>>> and more. She is also helping to write the text about the individual >>>>>> services that is currently on >>>>>> http://www.kbase.us/developer-zone/services/ . >>>>>> Elizabeth asked me for two pieces of information for each service: >>>>>> the >>>>>> git repo name and corresponding "human language" name of each >>>>>> service >>>>>> (for example, Central Store Service is in the kb_seed repo--you'd >>>>>> never >>>>>> guess that if you didn't already know), and also whether the service >>>>>> is >>>>>> internal-only or user-facing. I think this information would be >>>>>> useful to >>>>>> have on the Services spreadsheet (in fact, that spreadsheet used to >>>>>> have >>>>>> the human and git repo names for each service, but lost that at some >>>>>> point), but it already has a lot of columns, so I'd like permission >>>>>> to >>>>>> add those two. >>>>>> The Feb 4 Major tab >>>>>> >>>>>> (https://docs.google.com/a/lbl.gov/spreadsheet/ccc?key=0Ana5oznWypH2dFp >>>>>> paE >>>>>> JzOUdfMV8zN0Y3Vm5YM095aWc#gid=14) is empty so far, so maybe we can >>>>>> start >>>>>> from scratch and think about what columns make sense. There were >>>>>> some on >>>>>> the previous tabs that we probably don't need anymore. >>>>>> Thanks, >>>>>> Nomi Harris >>>>>> Project Manager, KBase >>>>>> >>>>>> _______________________________________________ >>>>>> Release-team mailing list >>>>>> Release-team(a)lists.kbase.us >>>>>> https://lists.kbase.us/mailman/listinfo/release-team >>>>> >>>>> _______________________________________________ >>>>> Release-team mailing list >>>>> Release-team(a)lists.kbase.us >>>>> https://lists.kbase.us/mailman/listinfo/release-team >>>>> >>> >>> _______________________________________________ >>> Release-team mailing list >>> Release-team(a)lists.kbase.us >>> https://lists.kbase.us/mailman/listinfo/release-team >> >> _______________________________________________ >> Release-team mailing list >> Release-team(a)lists.kbase.us >> https://lists.kbase.us/mailman/listinfo/release-team > > Thomas Brettin > 865-603-7760 (cell) > brettin(a)mcs.anl.gov > > > > _______________________________________________ > Release-team mailing list > Release-team(a)lists.kbase.us > https://lists.kbase.us/mailman/listinfo/release-team > Thomas Brettin 865-603-7760 (cell) brettin(a)mcs.anl.gov

1 0

Re: [Release-team] Adding columns to services spreadsheet
by Land, Miriam L. 01 Feb '13

01 Feb '13

In my opinion, the Master tab is a good place to place information that is stable from release to release. I have added a science domain column. I noticed that the 'Module Description' from the git repo and much less informative than what we have on the web. I'm not sure if it is very useful at the moment. I do like having a place to remind ourselves what is private (unadvertised) and what is public. Miriam On 1/31/13 12:49 PM, "Elizabeth M. Glass" <marland(a)mcs.anl.gov> wrote: >Can we also add in a column on what science domains these services work >for? M, MC, P > >Elizabeth > >----- Original Message ----- >From: Thomas Brettin <brettin(a)mcs.anl.gov> >To: Miriam L. Land <landml(a)ornl.gov> >Cc: release-team(a)lists.kbase.us, Nomi Harris <nlharris(a)lbl.gov> >Sent: Thu, 31 Jan 2013 07:09:21 -0600 (CST) >Subject: Re: [Release-team] Adding columns to services spreadsheet > >I want to keep all tabs. I plan to mine this data for research on the >progression of the development of a release infrastructure. > >Tom > >On Jan 31, 2013, at 7:05 AM, "Land, Miriam L." <landml(a)ornl.gov> wrote: > >> I'm in favor of a master tab. It would be very useful when I need to >>look >> up something that was somewhere in an earlier build. >> >> I also don't have a problem deleting the tabs that came before Nov >>Build, >> as long as we capture information on old modules that may come up again. >> >> I think the git repo is a great place to start parsing out the >> descriptions. >> >> Until the redeploy happens this morning, I have time to get this >>started. >> >> Miriam >> >> On 1/30/13 5:50 PM, "Nomi Harris" <nlharris(a)lbl.gov> wrote: >> >>> Right, I don't want to add another doc either! That's why I was asking >>>if >>> I could just add these two columns to the Services doc. I think they'd >>>be >>> useful to the people who are on the Build teams as well (maybe not so >>> much to the people on the release team, since we already pretty much >>>know >>> the info that will be in those columns). >>> I'm ok with either adding it to the Feb tab or making a new "master" >>>tab. >>> Nomi Harris >>> Project Manager, KBase >>> >>> On Jan 30, 2013, at 1:33 PM, Dan Olson <dolson(a)mcs.anl.gov> wrote: >>> >>>> I'm all for adding a "master" tab to the services spreadsheet with the >>>> static information that doesn't change every release. >>>> >>>> I really don't want to add another doc - right now we have - >>>> A punch list doc >>>> An email template doc >>>> A trac wiki page >>>> A services spreadsheet >>>> >>>> As time goes on the more info repositories we have the more >>>>opportunity >>>> for them >>>> to diverge and confusion to occur. >>>> >>>> ----- Original Message ----- >>>>> From: "Miriam L. Land" <landml(a)ornl.gov> >>>>> To: "Nomi Harris" <nlharris(a)lbl.gov>, release-team(a)lists.kbase.us >>>>> Sent: Wednesday, January 30, 2013 3:25:48 PM >>>>> Subject: Re: [Release-team] Adding columns to services spreadsheet >>>>> >>>>> Would it make sense to put the common name, repo name, contact(s), >>>>> and >>>>> description in a doc by itself? It could be cumulative across all >>>>> releases. >>>>> >>>>> Miriam >>>>> >>>>> On 1/30/13 3:39 PM, "Nomi Harris" <nlharris(a)lbl.gov> wrote: >>>>> >>>>>> Today I talked to Elizabeth, who is starting to work on materials >>>>>> for the >>>>>> User Zone on the website, which will include tutorials, a new User >>>>>> Guide, >>>>>> and more. She is also helping to write the text about the individual >>>>>> services that is currently on >>>>>> http://www.kbase.us/developer-zone/services/ . >>>>>> Elizabeth asked me for two pieces of information for each service: >>>>>> the >>>>>> git repo name and corresponding "human language" name of each >>>>>> service >>>>>> (for example, Central Store Service is in the kb_seed repo--you'd >>>>>> never >>>>>> guess that if you didn't already know), and also whether the service >>>>>> is >>>>>> internal-only or user-facing. I think this information would be >>>>>> useful to >>>>>> have on the Services spreadsheet (in fact, that spreadsheet used to >>>>>> have >>>>>> the human and git repo names for each service, but lost that at some >>>>>> point), but it already has a lot of columns, so I'd like permission >>>>>> to >>>>>> add those two. >>>>>> The Feb 4 Major tab >>>>>> >>>>>> >>>>>>(https://docs.google.com/a/lbl.gov/spreadsheet/ccc?key=0Ana5oznWypH2d >>>>>>Fp >>>>>> paE >>>>>> JzOUdfMV8zN0Y3Vm5YM095aWc#gid=14) is empty so far, so maybe we can >>>>>> start >>>>>> from scratch and think about what columns make sense. There were >>>>>> some on >>>>>> the previous tabs that we probably don't need anymore. >>>>>> Thanks, >>>>>> Nomi Harris >>>>>> Project Manager, KBase >>>>>> >>>>>> _______________________________________________ >>>>>> Release-team mailing list >>>>>> Release-team(a)lists.kbase.us >>>>>> https://lists.kbase.us/mailman/listinfo/release-team >>>>> >>>>> _______________________________________________ >>>>> Release-team mailing list >>>>> Release-team(a)lists.kbase.us >>>>> https://lists.kbase.us/mailman/listinfo/release-team >>>>> >>> >>> _______________________________________________ >>> Release-team mailing list >>> Release-team(a)lists.kbase.us >>> https://lists.kbase.us/mailman/listinfo/release-team >> >> _______________________________________________ >> Release-team mailing list >> Release-team(a)lists.kbase.us >> https://lists.kbase.us/mailman/listinfo/release-team > >Thomas Brettin >865-603-7760 (cell) >brettin(a)mcs.anl.gov > > > >_______________________________________________ >Release-team mailing list >Release-team(a)lists.kbase.us >https://lists.kbase.us/mailman/listinfo/release-team >

1 0

Re: [Release-team] Where is that documentation??
by Land, Miriam L. 01 Feb '13

01 Feb '13

I have drafted a 'Standard Documents' page at: https://trac.kbase.us/projects/kbase/wiki/StandardDocuments It could probably be expanded to include what is required, but for now, it is a straw man. Miriam On 1/31/13 5:26 PM, "Nomi Harris" <nlharris(a)lbl.gov> wrote: >Thanks, Miriam, this is a much-needed reference page. Please go ahead and >set it up and then people can edit if needed. > Nomi Harris > Project Manager, KBase > >On Jan 31, 2013, at 12:46 PM, "Land, Miriam L." <landml(a)ornl.gov> wrote: > >> All, >> >> The following started with a simple question from a developer, "Where >>do I put KBase documentation?" I couldn't find a clear and concise >>answer documented anywhere and it seems that the answer depends on what >>they mean by "documentation". >> >> By poking around, I have concluded that user manuals are in the >>docs.git repo under user_manuals/<module_name> while the tutorials are >>also in the docs.git repo but under <module_name>/tutorials (flipped >>order). There are HTML files in the docs.git repo under >><module_name>/API but it is not clear if there is any relationship to >>the HTML generated out of the type spec, and >>http://kbase.us/services/docs. I can't find documentation on who is >>responsible for writing some of these files and how these get propagated >>to the web (I've overheard oral instructions but little in writing). In >>addition to the type spec and multiple locations in the docs.git repo, >>we have the release notes which are part of the module repo with no >>specific file name and service descriptions developers supply through >>email at some point. I know we are evolving and defining things as we >>go along, but wouldn't you find this confusing at first? >> >> Most developers eventually find out all this through email exchanges. >>Would anyone mind if I started a trac page that lists the mandatory >>files/information which we expect developers to produce? My first draft >>is below. >> >> Miriam >> -------------------------------------- >> Type Spec - >> >> * A controlled vocabulary for defining methods and types for a >>module. The type compiler converts this into a standard directory >>structure and stubs for necessary files. >> * Recommended naming convention is <module_name>.spec >> * >>https://trac.kbase.us/projects/kbase/attachment/wiki/API/Type_compiler.pd >>f >> >> DEPENDENCIES >> >> * A required file in the module top dir that lists dependencies >> * https://trac.kbase.us/projects/kbase/wiki/IndependentBuild >> >> deploy.cfg >> >> * Located in the module top dir and is needed for deployments >> * https://trac.kbase.us/projects/kbase/wiki/DeployCfgStandards >> >> Makefile >> >> * Located in the module top dir and is used in deployment, document >>generation, and testing >> * Example Makefile is part of the dev_container/docs/module.Makefile >> * Standard Makefile Targets - >>https://trac.kbase.us/projects/kbase/wiki/MakefileTargets >> >> Release Notes >> >> * A file in the module top dir with a name that a human would >>recognize as a release note (e.g., Release_notes_01Jan2013). >> * https://trac.kbase.us/projects/kbase/wiki/ReleaseNotesStyle >> >> Technical Documentation >> >> * information imbedded within the type spec document that describes >>methods and types. >> * The document is auto-generated when the type spec is complied and >>it is copied the /kb/deployment/services/<module_name>/webroot during >>deployment. >> * Can be accessed through http://kbase.us/services/docs/<module_name>. >> * https://trac.kbase.us/projects/kbase/wiki/DocStructures >> >> User Manual >> >> * Comprehensive documentation of methods and types. More detailed >>than technical documentation and more comprehensive that a tutorial. >> * Created from scratch and it committed to the docs.git repo under >>the user_manuals/<module_name> directory. >> * https://trac.kbase.us/projects/kbase/wiki/UserManuals >> >> Tutorials >> >> * A guided tour through a typical usage pattern for the module. >> * Created from scratch and it is committed to the docs.git repo under >><module_name>/tutorials. >> * >>https://docs.google.com/document/d/1IxUo3kSWStE6rPYWemY_RmVyPA36lYNDa9QOp >>yxPvbg/edit (note, not at trac) >> >> >> _______________________________________________ >> Release-team mailing list >> Release-team(a)lists.kbase.us >> https://lists.kbase.us/mailman/listinfo/release-team >

1 0

Re: [Release-team] Where is that documentation??
by Nomi Harris 31 Jan '13

31 Jan '13

Thanks, Miriam, this is a much-needed reference page. Please go ahead and set it up and then people can edit if needed. Nomi Harris Project Manager, KBase On Jan 31, 2013, at 12:46 PM, "Land, Miriam L." <landml(a)ornl.gov> wrote: > All, > > The following started with a simple question from a developer, "Where do I put KBase documentation?" I couldn't find a clear and concise answer documented anywhere and it seems that the answer depends on what they mean by "documentation". > > By poking around, I have concluded that user manuals are in the docs.git repo under user_manuals/<module_name> while the tutorials are also in the docs.git repo but under <module_name>/tutorials (flipped order). There are HTML files in the docs.git repo under <module_name>/API but it is not clear if there is any relationship to the HTML generated out of the type spec, and http://kbase.us/services/docs. I can't find documentation on who is responsible for writing some of these files and how these get propagated to the web (I've overheard oral instructions but little in writing). In addition to the type spec and multiple locations in the docs.git repo, we have the release notes which are part of the module repo with no specific file name and service descriptions developers supply through email at some point. I know we are evolving and defining things as we go along, but wouldn't you find this confusing at first? > > Most developers eventually find out all this through email exchanges. Would anyone mind if I started a trac page that lists the mandatory files/information which we expect developers to produce? My first draft is below. > > Miriam > -------------------------------------- > Type Spec - > > * A controlled vocabulary for defining methods and types for a module. The type compiler converts this into a standard directory structure and stubs for necessary files. > * Recommended naming convention is <module_name>.spec > * https://trac.kbase.us/projects/kbase/attachment/wiki/API/Type_compiler.pdf > > DEPENDENCIES > > * A required file in the module top dir that lists dependencies > * https://trac.kbase.us/projects/kbase/wiki/IndependentBuild > > deploy.cfg > > * Located in the module top dir and is needed for deployments > * https://trac.kbase.us/projects/kbase/wiki/DeployCfgStandards > > Makefile > > * Located in the module top dir and is used in deployment, document generation, and testing > * Example Makefile is part of the dev_container/docs/module.Makefile > * Standard Makefile Targets - https://trac.kbase.us/projects/kbase/wiki/MakefileTargets > > Release Notes – > > * A file in the module top dir with a name that a human would recognize as a release note (e.g., Release_notes_01Jan2013). > * https://trac.kbase.us/projects/kbase/wiki/ReleaseNotesStyle > > Technical Documentation – > > * information imbedded within the type spec document that describes methods and types. > * The document is auto-generated when the type spec is complied and it is copied the /kb/deployment/services/<module_name>/webroot during deployment. > * Can be accessed through http://kbase.us/services/docs/<module_name>. > * https://trac.kbase.us/projects/kbase/wiki/DocStructures > > User Manual – > > * Comprehensive documentation of methods and types. More detailed than technical documentation and more comprehensive that a tutorial. > * Created from scratch and it committed to the docs.git repo under the user_manuals/<module_name> directory. > * https://trac.kbase.us/projects/kbase/wiki/UserManuals > > Tutorials – > > * A guided tour through a typical usage pattern for the module. > * Created from scratch and it is committed to the docs.git repo under <module_name>/tutorials. > * https://docs.google.com/document/d/1IxUo3kSWStE6rPYWemY_RmVyPA36lYNDa9QOpyx… (note, not at trac) > > > _______________________________________________ > Release-team mailing list > Release-team(a)lists.kbase.us > https://lists.kbase.us/mailman/listinfo/release-team

1 0

Re: [Release-team] Where is that documentation??
by Land, Miriam L. 31 Jan '13

31 Jan '13

I welcome any attempts to improve on the list. I think user's would love to see explanations of anything automatically generated or pushed to the web. They like to understand the consequences of choices they make. Miriam On 1/31/13 3:49 PM, "Thomas Brettin" <brettin(a)mcs.anl.gov> wrote: >This looks great, there is one issue, that is the automatically generated >documentation that we are planning to extract from the --help flag to all >commands. This will be deployed to webroot and injejested by Neal into >the developer's zone. > >Tom > > >On Jan 31, 2013, at 2:46 PM, "Land, Miriam L." <landml(a)ornl.gov> wrote: > >> All, >> >> The following started with a simple question from a developer, "Where >>do I put KBase documentation?" I couldn't find a clear and concise >>answer documented anywhere and it seems that the answer depends on what >>they mean by "documentation". >> >> By poking around, I have concluded that user manuals are in the >>docs.git repo under user_manuals/<module_name> while the tutorials are >>also in the docs.git repo but under <module_name>/tutorials (flipped >>order). There are HTML files in the docs.git repo under >><module_name>/API but it is not clear if there is any relationship to >>the HTML generated out of the type spec, and >>http://kbase.us/services/docs. I can't find documentation on who is >>responsible for writing some of these files and how these get propagated >>to the web (I've overheard oral instructions but little in writing). In >>addition to the type spec and multiple locations in the docs.git repo, >>we have the release notes which are part of the module repo with no >>specific file name and service descriptions developers supply through >>email at some point. I know we are evolving and defining things as we >>go along, but wouldn't you find this confusing at first? >> >> Most developers eventually find out all this through email exchanges. >>Would anyone mind if I started a trac page that lists the mandatory >>files/information which we expect developers to produce? My first draft >>is below. >> >> Miriam >> -------------------------------------- >> Type Spec - >> >> * A controlled vocabulary for defining methods and types for a >>module. The type compiler converts this into a standard directory >>structure and stubs for necessary files. >> * Recommended naming convention is <module_name>.spec >> * >>https://trac.kbase.us/projects/kbase/attachment/wiki/API/Type_compiler.pd >>f >> >> DEPENDENCIES >> >> * A required file in the module top dir that lists dependencies >> * https://trac.kbase.us/projects/kbase/wiki/IndependentBuild >> >> deploy.cfg >> >> * Located in the module top dir and is needed for deployments >> * https://trac.kbase.us/projects/kbase/wiki/DeployCfgStandards >> >> Makefile >> >> * Located in the module top dir and is used in deployment, document >>generation, and testing >> * Example Makefile is part of the dev_container/docs/module.Makefile >> * Standard Makefile Targets - >>https://trac.kbase.us/projects/kbase/wiki/MakefileTargets >> >> Release Notes >> >> * A file in the module top dir with a name that a human would >>recognize as a release note (e.g., Release_notes_01Jan2013). >> * https://trac.kbase.us/projects/kbase/wiki/ReleaseNotesStyle >> >> Technical Documentation >> >> * information imbedded within the type spec document that describes >>methods and types. >> * The document is auto-generated when the type spec is complied and >>it is copied the /kb/deployment/services/<module_name>/webroot during >>deployment. >> * Can be accessed through http://kbase.us/services/docs/<module_name>. >> * https://trac.kbase.us/projects/kbase/wiki/DocStructures >> >> User Manual >> >> * Comprehensive documentation of methods and types. More detailed >>than technical documentation and more comprehensive that a tutorial. >> * Created from scratch and it committed to the docs.git repo under >>the user_manuals/<module_name> directory. >> * https://trac.kbase.us/projects/kbase/wiki/UserManuals >> >> Tutorials >> >> * A guided tour through a typical usage pattern for the module. >> * Created from scratch and it is committed to the docs.git repo under >><module_name>/tutorials. >> * >>https://docs.google.com/document/d/1IxUo3kSWStE6rPYWemY_RmVyPA36lYNDa9QOp >>yxPvbg/edit (note, not at trac) >> >> >> _______________________________________________ >> Release-team mailing list >> Release-team(a)lists.kbase.us >> https://lists.kbase.us/mailman/listinfo/release-team > >Thomas Brettin >865-603-7760 (cell) >brettin(a)mcs.anl.gov > > >

1 0

Re: [Release-team] Where is that documentation??
by Thomas Brettin 31 Jan '13

31 Jan '13

This looks great, there is one issue, that is the automatically generated documentation that we are planning to extract from the --help flag to all commands. This will be deployed to webroot and injejested by Neal into the developer's zone. Tom On Jan 31, 2013, at 2:46 PM, "Land, Miriam L." <landml(a)ornl.gov> wrote: > All, > > The following started with a simple question from a developer, "Where do I put KBase documentation?" I couldn't find a clear and concise answer documented anywhere and it seems that the answer depends on what they mean by "documentation". > > By poking around, I have concluded that user manuals are in the docs.git repo under user_manuals/<module_name> while the tutorials are also in the docs.git repo but under <module_name>/tutorials (flipped order). There are HTML files in the docs.git repo under <module_name>/API but it is not clear if there is any relationship to the HTML generated out of the type spec, and http://kbase.us/services/docs. I can't find documentation on who is responsible for writing some of these files and how these get propagated to the web (I've overheard oral instructions but little in writing). In addition to the type spec and multiple locations in the docs.git repo, we have the release notes which are part of the module repo with no specific file name and service descriptions developers supply through email at some point. I know we are evolving and defining things as we go along, but wouldn't you find this confusing at first? > > Most developers eventually find out all this through email exchanges. Would anyone mind if I started a trac page that lists the mandatory files/information which we expect developers to produce? My first draft is below. > > Miriam > -------------------------------------- > Type Spec - > > * A controlled vocabulary for defining methods and types for a module. The type compiler converts this into a standard directory structure and stubs for necessary files. > * Recommended naming convention is <module_name>.spec > * https://trac.kbase.us/projects/kbase/attachment/wiki/API/Type_compiler.pdf > > DEPENDENCIES > > * A required file in the module top dir that lists dependencies > * https://trac.kbase.us/projects/kbase/wiki/IndependentBuild > > deploy.cfg > > * Located in the module top dir and is needed for deployments > * https://trac.kbase.us/projects/kbase/wiki/DeployCfgStandards > > Makefile > > * Located in the module top dir and is used in deployment, document generation, and testing > * Example Makefile is part of the dev_container/docs/module.Makefile > * Standard Makefile Targets - https://trac.kbase.us/projects/kbase/wiki/MakefileTargets > > Release Notes – > > * A file in the module top dir with a name that a human would recognize as a release note (e.g., Release_notes_01Jan2013). > * https://trac.kbase.us/projects/kbase/wiki/ReleaseNotesStyle > > Technical Documentation – > > * information imbedded within the type spec document that describes methods and types. > * The document is auto-generated when the type spec is complied and it is copied the /kb/deployment/services/<module_name>/webroot during deployment. > * Can be accessed through http://kbase.us/services/docs/<module_name>. > * https://trac.kbase.us/projects/kbase/wiki/DocStructures > > User Manual – > > * Comprehensive documentation of methods and types. More detailed than technical documentation and more comprehensive that a tutorial. > * Created from scratch and it committed to the docs.git repo under the user_manuals/<module_name> directory. > * https://trac.kbase.us/projects/kbase/wiki/UserManuals > > Tutorials – > > * A guided tour through a typical usage pattern for the module. > * Created from scratch and it is committed to the docs.git repo under <module_name>/tutorials. > * https://docs.google.com/document/d/1IxUo3kSWStE6rPYWemY_RmVyPA36lYNDa9QOpyx… (note, not at trac) > > > _______________________________________________ > Release-team mailing list > Release-team(a)lists.kbase.us > https://lists.kbase.us/mailman/listinfo/release-team Thomas Brettin 865-603-7760 (cell) brettin(a)mcs.anl.gov

1 0

Where is that documentation??
by Land, Miriam L. 31 Jan '13

31 Jan '13

All, The following started with a simple question from a developer, "Where do I put KBase documentation?" I couldn't find a clear and concise answer documented anywhere and it seems that the answer depends on what they mean by "documentation". By poking around, I have concluded that user manuals are in the docs.git repo under user_manuals/<module_name> while the tutorials are also in the docs.git repo but under <module_name>/tutorials (flipped order). There are HTML files in the docs.git repo under <module_name>/API but it is not clear if there is any relationship to the HTML generated out of the type spec, and http://kbase.us/services/docs. I can't find documentation on who is responsible for writing some of these files and how these get propagated to the web (I've overheard oral instructions but little in writing). In addition to the type spec and multiple locations in the docs.git repo, we have the release notes which are part of the module repo with no specific file name and service descriptions developers supply through email at some point. I know we are evolving and defining things as we go along, but wouldn't you find this confusing at first? Most developers eventually find out all this through email exchanges. Would anyone mind if I started a trac page that lists the mandatory files/information which we expect developers to produce? My first draft is below. Miriam -------------------------------------- Type Spec - * A controlled vocabulary for defining methods and types for a module. The type compiler converts this into a standard directory structure and stubs for necessary files. * Recommended naming convention is <module_name>.spec * https://trac.kbase.us/projects/kbase/attachment/wiki/API/Type_compiler.pdf DEPENDENCIES * A required file in the module top dir that lists dependencies * https://trac.kbase.us/projects/kbase/wiki/IndependentBuild deploy.cfg * Located in the module top dir and is needed for deployments * https://trac.kbase.us/projects/kbase/wiki/DeployCfgStandards Makefile * Located in the module top dir and is used in deployment, document generation, and testing * Example Makefile is part of the dev_container/docs/module.Makefile * Standard Makefile Targets - https://trac.kbase.us/projects/kbase/wiki/MakefileTargets Release Notes – * A file in the module top dir with a name that a human would recognize as a release note (e.g., Release_notes_01Jan2013). * https://trac.kbase.us/projects/kbase/wiki/ReleaseNotesStyle Technical Documentation – * information imbedded within the type spec document that describes methods and types. * The document is auto-generated when the type spec is complied and it is copied the /kb/deployment/services/<module_name>/webroot during deployment. * Can be accessed through http://kbase.us/services/docs/<module_name>. * https://trac.kbase.us/projects/kbase/wiki/DocStructures User Manual – * Comprehensive documentation of methods and types. More detailed than technical documentation and more comprehensive that a tutorial. * Created from scratch and it committed to the docs.git repo under the user_manuals/<module_name> directory. * https://trac.kbase.us/projects/kbase/wiki/UserManuals Tutorials – * A guided tour through a typical usage pattern for the module. * Created from scratch and it is committed to the docs.git repo under <module_name>/tutorials. * https://docs.google.com/document/d/1IxUo3kSWStE6rPYWemY_RmVyPA36lYNDa9QOpyx… (note, not at trac)

1 0

Re: [Release-team] Tech doc testing--need to send out failure notices?
by Nomi Harris 31 Jan '13

31 Jan '13

Cool, thanks. Nomi Harris Project Manager, KBase On Jan 31, 2013, at 10:27 AM, Thomas Brettin <brettin(a)mcs.anl.gov> wrote: > In an automated process we wouldn't check the tec docs if it fails deploy. > > > On Jan 31, 2013, at 12:18 PM, "Land, Miriam L." <landml(a)ornl.gov> wrote: > >> Nomi, >> >> On 1/31/13 1:19 AM, "Nomi Harris" <nlharris(a)lbl.gov> wrote: >> >>> I checked the API docs. 8 of the 11 modules failed, but I notice that >>> most of these failed to pass initial deploy, so I guess they never got to >>> the "make deploy-docs" part of the build process. I don't need to notify >>> the authors of those modules about their tech doc failure when they >>> failed deploy, do I? >> >> I wouldn't think so. >> >>> The only module that passed deploy and testing that failed doc was >>> sim_service, which still doesn't have a deploy-docs target. I think its >>> author has been busy with other stuff. :-) >> >> Yeah, probably busy. >> >>> KBaseFBAModeling passed tech doc but failed initial testing. >>> protein_info_service passed tech doc but failed initial deploy. >>> Only ONE module passed everything so far: translation. >> >> Considering its history, that is a big success. >> >> Miriam >> >>> Nomi

1 0

Re: [Release-team] Tech doc testing--need to send out failure notices?
by Thomas Brettin 31 Jan '13

31 Jan '13

In an automated process we wouldn't check the tec docs if it fails deploy. On Jan 31, 2013, at 12:18 PM, "Land, Miriam L." <landml(a)ornl.gov> wrote: > Nomi, > > On 1/31/13 1:19 AM, "Nomi Harris" <nlharris(a)lbl.gov> wrote: > >> I checked the API docs. 8 of the 11 modules failed, but I notice that >> most of these failed to pass initial deploy, so I guess they never got to >> the "make deploy-docs" part of the build process. I don't need to notify >> the authors of those modules about their tech doc failure when they >> failed deploy, do I? > > I wouldn't think so. > >> The only module that passed deploy and testing that failed doc was >> sim_service, which still doesn't have a deploy-docs target. I think its >> author has been busy with other stuff. :-) > > Yeah, probably busy. > >> KBaseFBAModeling passed tech doc but failed initial testing. >> protein_info_service passed tech doc but failed initial deploy. >> Only ONE module passed everything so far: translation. > > Considering its history, that is a big success. > > Miriam > >> Nomi >> >> _______________________________________________ >> Release-team mailing list >> Release-team(a)lists.kbase.us >> https://lists.kbase.us/mailman/listinfo/release-team > > _______________________________________________ > Release-team mailing list > Release-team(a)lists.kbase.us > https://lists.kbase.us/mailman/listinfo/release-team Thomas Brettin 865-603-7760 (cell) brettin(a)mcs.anl.gov

1 0