Information and Guidelines for Fermitools Product Providers Information and Background - Guidelines - Templates The Fermitools software project was initiated as a way to foster collaborative sharing and improvement of software products developed at Fermilab. Originally conceived as a strategy for broadening the use, and thereby strengthening the implementation, of a wide variety of software developed by Fermilab's Computing Division, the project has expanded to include software contributed by others working at Fermilab. To facilitate the addition of more software products, we have compiled this information about the project and the Guidelines for product developers who wish to contribute their software. Information and Background Since the goal of Fermitools is to widen the use of the software, we strive to make participation as straightforward as possible. We must conform to certain Fermilab and DOE rules, and need to keep the management of the program economical. Therefore, we request that Product Providers observe the following: Package the software product and coordinate with the Fermitools librarian to copy the files to KITS and/or ftp.fnal.gov/pub. Include all the required files in the software. Document the software. Test that the software can be extracted from the package, built and run as described in the included documentation. Help the Fermitools Librarian establish a support email address xyz-support@fnal.gov - where 'xyz' is the name of the software, and be included on this email alias. Answer mail sent to the software support alias in a timely manner. Cooperate with the Fermitools Working Group on reports, statistics, meetings, etc. It is our experience that setting up a listserve or discussion group for a particular product is an especially beneficial way of facilitating interaction among users of the product. Users can share ideas and enhancements immediately without waiting for an entire new version. Distribution of Fermitools Fermitools products are obtained from http://fermitools.fnal.gov/, generally available as tar files. They are also available through the Fermilab-supported user distribution repository called KITS. The only difference is that access to KITS is restricted to Fermilab users, and by putting software into Fermitools, it can be shared with a wider community. Some products are designated as Special Products if they involve non-standard conditions or special assistance for their use. In some cases, the correct configuration of the software will be site dependent and cannot be determined a priori. This software is made available under a slightly different arrangement. The new user will be registered and consult with the Product Provider for agreement on support issues and/or information about the special or restrictive features. If a candidate product has features or conditions that may require offering as a Special Product, the Fermitools Librarian will assist the Product Provider with the necessary preparations. The Fermitools Web Pages The Fermitools Web pages provide the most visible frontend to the project. Products are listed with links to their Abstract. This serves as a 'front page' for the product, and typically is a brief product description. Currently, the Abstract page is designed with preset links to the README file, the software itself, any Documentation, and web pages for the product. We are expecting to be able to offer Product Providers assistance in designing and creating web pages for their product in the future. Software Packaging It is our intention that software products be packaged as a file that can be copied over the network using ftp or to recording media using standard copying programs. Each product has an assigned directory for each version of the product. In general, the guidelines for contributing products follow the conventions of the UPS Software at Fermilab. This allows for more efficient overall product management by Computing Division staff, and the use of some automated processes. If any deviation from the regular format is anticipated, the Product Provider should consult with the Fermitools Librarian to determine how these exceptions will be handled. A detailed description of the various components of the software distribution file are given below in the "Guidelines" section. Some of the text is required for the inclusion of a product in Fermitools; this is provided verbatim. Other parts are reasonably standard, and a template is supplied for convenience. We recommend using templates wherever they are available. Product Providers are encouraged to include other helpful or additional information about the product, especially through Web links referenced in the standard formats. The Fermitools Web pages are designed to maximize access to information about Fermitools and the products in it. The Fermitools Working Group Members of several Departments in the Computing Division currently comprise the Fermitools Working Group. It handles the bureaucratic and technical aspects of the project such as: Reviewing proposals for inclusion of software packages Monitoring the status and support load of the program and the included software Reviewing user feedback and the software that is included Interacting with the Office of Research & Technology Applications Providing general guidance to program management. The Working Group meets regularly and assists the Librarian in managing and maintaining the project. It also prepares reports for division management about activity in the program and interfaces to Fermilab administration in unusual cases or on special issues. Issues of concern can be brought to the attention of the Working Group by sending email to the Fermitools Librarian. Re-Distribution of Fermitools Software products contributed to Fermitools can be freely re-distributed as long as the following conditions are met: The product's Fermitools README file (including the required Terms and Conditions) is included in any re-distribution, and if the re-distribution will be in a commercial product, special conditions are met. This is handled through interaction with the Office of Research & Technology Applications at Fermilab. For Further Information Fermitools web page: http://fermitools.fnal.gov/ Specific questions: please email the Fermitools Librarian Guidelines Perhaps one of the best ways to prepare a product for Fermitools is to examine the files and associated materials for a similar product that is already in the program. We have attempted to make the 'build' of the files as straightforward as possible, and have designed a set of web-based templates to facilitate that process. The final package that is assembled and delivered to the Fermitools Librarian consists of a set of required files, some of which are static in content and some of which are static in format. A final review of the product files before release through Fermitools is done to assure that the required files are included in the necessary format. Any deviations must be discussed with the Fermitools Librarian prior to creating the files. Required Files The following files must be created for all software packages: The Sources - Code, Makefiles, etc. Documentation Test Programs ABSTRACT (see ABSTRACT template) Fermitools README (see README template): Those in all capital letters are specified files for which the words themselves or templates are provided. Since these are handled in an automated process, the naming of certain files must be strictly followed. The links are to template or sample files which a Product Provider should use. The templates are referenced below. If the product is already in KITS, it is likely that only the Fermitools README and ABSTRACT files will need to be created. Consult with the Librarian to determine what is necessary. Description of Files The Sources All the source code, header files, makefiles, and data files needed to build and configure the software in its final form on at least one computer platform, must be included. The only exceptions are for those explicitly provided by other software in the Fermitools Software Program or other software available from other sources - either free or commercially. There is no commitment nor guarantee that the software can be built, configured or run on platforms other than those explicitly listed in the documentation that is included in the software package. Documentation Files should be included in the software package which provide user documentation for the software. Wherever possible "on-line help" documentation in a form appropriate for the platform on which the software will run (e.g., man pages) should be provided. Internal documentation specifying the architecture and internals of the software shall be provided with the software. This can be at an appropriate level of detail for the software package it describes, e.g. a paragraph is sufficient for a single file package, and a full internal architecture description for a complete software system. In general, this level of documentation will have naturally been developed as part of the development of the software itself. Tests All software packages should have a test program that can be built and run to verify correct installation and functioning of the software. Any tests developed in conjunction with the software should be packaged and distributed with it. ABSTRACT This should be no more than a half a page of description for the product. It is used to create the Fermitools web-page for the product. If you want to include links to other pages within the ABSTRACT, please create the file in HTML format; otherwise plain ASCII is just fine. README The README file gives a longer, more detailed description of the product. It should include the description, a pointer to documentation, notification of any required hardware and/or software, how to do the installation and how to run the software at a minimum. The Fermitools README also includes the required Terms and Conditions. Optional file The Product Provider is encouraged to provide a text file named WEB_LINKS in the product archive file. That file should contain URL links pointing to a WEB page for that product and/or to more documentation (e.g., a postscript file). In that file the keywords WEB_PAGE and DOC will be recognized, e.g. WEB_PAGE = http://www-pat.fnal.gov/nirvana/histo.html WEB_DOC = http://http://www-pat.fnal.gov/histo_doc/histo_ug.html Preparing the Product Files Product Providers should build their README file using the template. This can be saved to a local file for further editing, if desired. Any changes to required text will cause the product to be rejected in final review, so be sure no changes are made in this portion of the README file. Combine the README file with the other required files in an archive file and contact the Fermitools Librarian for instructions on how to complete the next step. In the case of some products in KITS, there may fewer steps needed. Contact the Librarian for information. The ABSTRACT and links to the product pages and information will be incorporated into the main Fermitools web page. Other links supplied by the Product Provider will also be made for the product. Templates and Files ABSTRACT This is a template for a product abstract. The page will have links to Fermitools Home, the product's README file, the software, documentation, the Product WWW Pages and an abstract containing a brief description of the software. Product Providers are encouraged to add more information in form of local files or links. README This is a template for a product README file. The minimum set of fields to be completed is: Product Name, Product Version, Date, Author(s), Author Mailstop, Product Description, Documentation. The others should be used as they are appropriate.

last modified 12/28/2007   fermitools_support@fnal.gov

Security, Privacy, Legal