Creating and releasing a Play 2 module

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

• The steps are based on how Play 2 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 2.3 are assumed to be part of the development environment
  • These instructions may also work for Play versions above 2.4 (not tested)
• UNIX commands are assumed to take place on the path determined by the most recently executed cd command

Create module

1. Create module: activator new

• Template: play-java
• Name: <module>
  • In Play 1, the module name must match regex [a-zA-Z]+

1. Move module to project-code subdirectory
2. mkdir project-code: this is the module's directory/Git repository
3. mv * project-code
4. cd project-code
5. Delete unnecessary content/files/directories:
6. vi conf/application.conf: delete all content
7. vi project/plugins.sbt: remove unnecessary plugins
8. Remove unnecessary files/directories. Examples: - public or its subdirectories - test/resources
9. vi .gitignore: include files specified in Appendix A
10. rm conf/routes
11. Build module
12. activator 1. run 1. Access localhost:9000 on a browser and fix any compilation issues
13. Eclipsify module
14. activator 1. eclipse
15. Import module project into Eclipse:

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

1. Set up module
2. Delete README
3. Create README.md
4. Set name, version (start with 0.1.0), organisation and dependencies in build.sbt
5. Implement the module
6. Delete the views package under app if the module won't provide views
7. Delete the controllers package under app if the module won't provide controllers
8. Add code to package <package>.<project> under app
9. Write and execute tests: activator test
10. Check that no code problems are reported by Eclipse
11. Check that no unnecessary logging is generated by the module (search the code for Logger)
12. Document the module
13. Document all API methods using Javadoc
14. activator publishLocal: Javadoc is generated under target
15. Check that: 1. All public API methods are documented 1. No module related Javadoc errors are found in log files (under the logs directory)
16. Add full documentation to README.md
17. Publish module to local Ivy repository
18. activator 1. clean 1. publishLocal: the module gets published under ~/.ivy2/local

Create module sample application

1. Create a directory for sample applications at the same level as project-code: mkdir samples
2. cd samples
3. activator new

• Template: play-java
• Name: <module>-sample

1. cd <module>-sample
2. Configure the sample application
3. Delete README
4. Add full documentation to README.md
5. Set name, version (start with 0.1.0, it should be in sync with the module one) and dependency to the module in build.sbt
6. Delete unnecessary files/directories. Examples:

• public or its subdirectories
• test/resources

1. vi .gitignore and include files specified in Appendix A
2. Eclipsify module sample application
3. activator 1. eclipse
4. Import module sample project into Eclipse:

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

1. Implement the module
2. Add code to under app
3. Write and execute tests: activator test
4. Test manually at localhost:9000
5. Check that no code problems are reported by Eclipse

Release module

1. Test module before publishing to GitHub
2. Remove module from .ivy2/local and .ivy2/cache
3. cd project-code
4. activator 1. clean 1. reload 1. update 1. Publish locally: publishLocal
   1. check that module is at .ivy2/local and not at .ivy2/cache
   2. Check that no unnecessary files/directories exist under `~/.ivy2/local//. If any, remove them and republish. Examples of unnecessary files/directories include:
   • Files: .classpath, .project, .gitignore
   • Directories: .settings, eclipse, javadoc, logs, .git, empty directories (e.g. public) 1. test: all tests should pass
5. Test module sample application against locally published module
6. cd samples/<module>-sample
7. activator 1. clean 1. reload 1. update 1. test: all tests should be ok 1. run and test manually
8. Create a release repository and push it to GitHub
9. Create a directory for the release repository outside the project one: mkdir ~/release
10. Add built module to it: cp -rv ~/.ivy2/local/<package>/<project*> ~/release
11. cd release
12. Add/commit release files to local Git repository: see Appendix B
13. Create GitHub release repository: see Appendix C
14. Push release files from local Git repository to GitHub release repository: see Appendix D
15. Test module sample application against GitHub published module
16. Remove module from .ivy2/local and .ivy2/cache
17. cd samples/<module>-sample
18. vi build.sbt and include GitHub release repository in resolvers
19. activator 1. clean 1. reload 1. update 1. test: all tests should be ok 1. run and test manually
20. Publish module in GitHub
21. Add/commit module files to local Git repository: see Appendix B
22. Create GitHub module repository: see Appendix C
23. Push module files from local Git repository to GitHub module repository: see Appendix D
24. Publish module sample in GitHub
25. Add/commit module sample files to local Git repository: see Appendix B
26. Create GitHub module sample repository: see Appendix C
27. Push module sample files from local Git repository to GitHub module sample repository: see Appendix D
28. Create module web page in GitHub: see Appendix E
29. Announce the module on the play-framework Google Group using the e-mail template specified in Appendix F

Appendix A - .gitignore

.gitignore should include at least the following files:

    .*
    !.gitignore
    logs
    target
    project/project
    project/target
    bin
    activator
    activator.bat
    activator-launch*

Other files may be considered for inclusion. Examples include:

    tmp
    .history
    dist
    /out
    /RUNNING_PID

Appendix B - Add/commit files to local Git repository

1. cd <directory>
2. git init
3. vi .gitignore: Appendix A includes examples of files to be Git ignored
4. vi README (recommended for all GitHub repositories)
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 "<commit message including 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 C - Create repository in GitHub

1. Create repository in GitHub:
2. Log in GitHub
3. New repository
4. Name: <repository>
5. Description (optional):
6. Public
7. Create repository
8. Note the repository SSH URL: git@github.com:<user>/<repository>.git

Appendix D - Push files from local Git repository to GitHub

1. cd <local repository>
2. Associate GitHub (remote) repository with local one: git remote add origin <repository SSH URL>
3. Push files from local repository to GitHub: git push -u origin master
4. Push tag to remote: git push origin <tagname> (e.g. git push origin 0.1.0)

Appendix E - Create module web page in GitHub

1. In Github, go to the repository, press Settings and then automatic page generator
2. Copy/paste the contents of the module's README.md file onto the body
3. Press "Continue to layouts"
4. Select layout
5. Preview page and check that everything's ok
6. Publish page

Appendix F - Module announcement e-mail template

Subject: [play-framework] [2.3.x] Play 2 <module> module
To: play-framework@googlegroups.com

The Play 2 <module> module <module description>. It has been published along with a sample application.

Website: https://<user>.github.io/play2-<module>/
Documentation: https://github.com/<user>/play2-<module>-sample/blob/master/README.md
Short description: The Play 2 <module> module <short description>.

References

• Writing modules for Play 2, part 1: Get something working - Objectify
• Writing modules for Play 2, part 2: Interceptors - Objectify
• Publishing Play 2 modules on github - Objectify
• playframework - How to define resolver for dependencies from custom repository on GitHub? - Stack Overflow