Creating and releasing a Play 1 module

The sections below describe the steps required to create and release a Play 1 module along with a corresponding sample application:

• The steps are based on how Play 1 Chart was created
• Some steps may be redundant or missing
• The order of the steps is not strict i.e. some steps may be executed earlier/later than specified
• Some steps may vary according to user preferences (e.g. preferred text editor)
• <> refers to a placeholder (e.g. <module> is a placeholder for a module name)
• Linux, Eclipse and Play 1.3 are assumed to be part of the development environment
• UNIX commands are assumed to take place on the path determined by the most recently executed cd command

Create module

1. Create module: play new-module <module>

• The module name must match regex [a-zA-Z]+

1. Build module: cd <module>; play build-module

• Press enter when asked about required Play Framework versions

1. Add JAR files required by the module to the lib directory
2. Eclipsify module: cd ..; play eclipsify <module>
3. Import module project into Eclipse:

• File -> Import -> General -> Existing Project into Workspace

1. Add module code to the src directory under package play.modules.<module>
2. Add module fast tags to under app/tags
3. Write and execute tests
4. Add documentation to documentation/manual/home.textile
5. Document all public API methods using Javadoc
6. Execute play javadoc and check that:
7. All public API methods are documented
8. No module related Javadoc errors are found in log files (under the logs directory)
9. Check that no code problems are reported by Eclipse
10. Check that no unnecessary logging is generated by the module (search the code for Logger)
11. Build module: cd <module>; play build-module

• Press enter when asked about required Play Framework versions

Create module sample application

1. Create sample application under the module's directory: cd <module>; play new samples-and-tests; cd samples-and-tests

• Enter Play <module> Module App when asked about the application name

1. Add samples-and-tests/app as a source folder in Eclipse (in order to navigate through source files)
2. Set <module> as a sample application's dependency during development: see Appendix A
3. Resolve dependencies: play deps
4. File <module> shows up under the modules directory and its content is the path to the module
5. Check that the module can be used:
6. play <module>:hello: Hello is displayed
7. play run: INFO ~ Module <module> is available (<path to module>) is displayed
8. Implement the sample application
9. Write and execute tests

Release module

1. cd <module>
2. Remove unnecessary files/directories (e.g. conf/messages, conf/routes)
3. rm -fr dist; play build-module

• Press enter when asked about required Play Framework versions

1. Test the sample application
2. cd samples-and-tests
3. play test and execute automated tests (http://localhost:9000/@tests)
4. play clean; play deps; play run and test manually (http://localhost:9000)
5. Configure the sample application for release
6. Add <module> as a sample application's dependency for release: see Appendix B
7. play deps; play clean
8. Remove unnecessary directories: javadoc, modules and test-result
9. Check that no unnecessary files exist
10. Configure the module for release and archive it
11. Set <module> dependencies for release: see Appendix C
12. cd <module>; rm -fr dist; play build-module - Press enter when asked about required Play Framework versions
13. A zip file is generated under <module>/dist
14. Exclude unnecessary files from the module's zip file: zip -d <module>-<version>.zip README commands.pyc
15. Exclude any other unnecessary files/directories: 1. Files: .classpath, .project, .gitignore 1. Directories: .settings, eclipse, javadoc, logs, .git, empty directories (e.g. public)
16. Archive the module's zip file under a release directory (e.g. outside the module directory, in a directory named <release date>)
17. rm -fr dist
18. Add module to local Git repository: see Appendix D
19. Publish module on GitHub: see Appendix E
20. Create module web page in GitHub: see Appendix F
21. Post a module registration request on the play-framework Google Group using the e-mail template specified in Appendix G

Appendix A - Sample application dependencies during development

In order to set <module> as a sample application's dependency during development, set the contents of the sample application's conf/dependencies.yml to:

# Application dependencies

require:
    - play
    - <module> -> <module> <version>

repositories:
    - <repository>:
        type: local
        artifact: "<path to module>"
        contains:
            - <module> -> *

where is the module version (e.g. 0.1).

NB: dependencies.yml must not include any tab characters.

Appendix B - Sample application dependencies for release

In order to set <module> as a sample application's dependency for release, set the contents of the sample application's conf/dependencies.yml to:

# Application dependencies

require:
    - play -> <module> <version>

where is the module version (e.g. 0.1).

NB: dependencies.yml must not include any tab characters.

Appendix C - Module dependencies for release

In order to configure the module's dependencies for release, set the contents of the module's conf/dependencies.yml to:

self: play -> <module> <version>

require:
    - <module>

where is the module version (e.g. 0.1).

NB: dependencies.yml must not include any tab characters.

Appendix D - Add module to local Git repository

1. cd <module_directory>

2. git init1. vi .gitignore and include (at least):

    .classpath
    eclipse
    .project
    .settings
    commands.pyc
   

3. vi .gitignore and include (at least):

    .classpath
    eclipse
    .project
    .settings
    commands.pyc
   

4. vi README (recommended for all GitHub repositories):

    # play1-<module>
    Play 1 <module> module
   
    Home page: http://<user>.github.io/play1-<module>/
   

5. vi LICENSE (recommended for all GitHub repositories)

6. git status: all files should be unstaged

7. Add all files recursively: git add .

8. git status: all files should be staged

9. Commit: git commit -m "Play 1 <module> module <version>"

10. Tag project: git tag <tagname> (e.g. git tag 0.1.0)

11. git status: all files should be committed i.e. on the master HEAD of the local copy

Appendix E - Publish module on GitHub

1. Create repository in GitHub:
2. Log in GitHub
3. New repository
4. Name: play1-<module>
5. Description (optional): Play 1 <module> module
6. Public
7. Create repository
8. Note the repository SSH URL: git@github.com:<user>/play1-<module>.git
9. Push local repository to GitHub one:
10. cd <module>
11. Associate GitHub (remote) repository with local one: git remote add origin <repository SSH URL>
12. Push files from local repository to GitHub: git push -u origin master
13. Push tag to remote: git push origin <tagname> (e.g. git push origin 0.1.0)

Appendix F - Create module web page in GitHub

1. cd <module release directory> (where the module's zip file resides)
2. Convert module's textile documentation to GitHub's markdown: pandoc <path to module>/documentation/manual/home.textile -t markdown -o home.md
3. In Github, go to the repository, press Settings and then automatic page generator
4. Copy/paste the contents of home.md onto the body
5. Press "Continue to layouts"
6. Select layout
7. Preview page and check that everything's ok, as GitHub Markdown is different from Markdown (adjust text if necessary)
8. Publish page

Appendix G - Module registration request e-mail template

Subject: [play-framework] [1.3.x] Module registration request: <module>
To: play-framework@googlegroups.com


Module name:
<module>
 
Display name:
<module display name>
 
Description:
The <module display name> module <module's purpose>.
 
Project home page:
http://<user>.github.io/<module repository name on GitHub>/

References

• Play modules
• Play Framework: Introduction to Writing Modules | PACKT Books