Skip to content

Latest commit

 

History

History
108 lines (77 loc) · 4.76 KB

DEVELOPING.md

File metadata and controls

108 lines (77 loc) · 4.76 KB
Raw

Development Guidelines

This document describes tools, tasks and workflow that one needs to be familiar with in order to effectively maintain this project. If you use this package within your own software as is but don't plan on modifying it, this guide is not for you.

Tools

  • Gradle: used to run predefined tasks. It also manages dependencies for the project. If you do not have it already installed, you won't need to install it. The gradle wrapper is included in the project and you can invoke it using ./gradlew substituted for gradle.

Tasks

Building

Gradle's Java Plugin provides various tasks to build this software. The most common tasks are:

  • gradle build - build jars and test
  • gradle clean - remove previously built artifacts.

Testing

This project's tests are written as JUnit test cases. Common tasks:

  • gradle check - run the test suite.

Generating Documentation

This project's reference documentation is generated by Javadoc and resides in the docs directory of the project. Common tasks:

  • gradle javadoc - generate the reference documentation locally.

Releasing

In order to create a release, the following should be completed in order.

  1. Ensure all the tests are passing (gradle check) and that there is enough test coverage.
  2. Make sure you are on the dev branch of the repository, with all changes merged/commited already.
  3. Update the version number in the source code and the README. See Versioning for information about selecting an appropriate version number. Files to change:
    • src/main/java/com/opentok/constants/Version.java
    • build.gradle
    • README.md
  4. Commit the version number change with the message "Update to version x.x.x", substituting the new version number.
  5. Create a git tag: git tag -a vx.x.x -m "Release vx.x.x"
  6. Ensure that you have permission to update the OSSRH repository. The following system properties must be set:
    • ossrhUsername
    • ossrhPassword
    • signing.keyId
    • signing.password
    • signing.secretKeyRingFile
  7. Run ./publish.sh to create a staging release.
  8. Login to OSSRH and promote the staging release to a public release.
  9. Change the version number for future development by incrementing the patch number and adding "-alpha.1" in each file except the README. Building may have generated the docs files once again, so to clear them run git checkout -- docs/. Then stage the remaining files and commit with the message "Begin development on next version".
  10. Push the changes to the source repository: git push origin dev; git push --tags origin
  11. Find the latest .jar in the build directory and upload this as an attached to the latest GitHub Release. Add release notes with a description of changes and fixes.

IDE Integration

Gradle's IDEA Plugin and Eclipse Plugin provide tasks to generate project files for these IDEs. In general, neither of these are necessary to work on the project. If you prefer to use one of these IDEs, you may find those tasks helpful.

Workflow

Versioning

The project uses semantic versioning as a policy for incrementing version numbers. For planned work that will go into a future version, there should be a Milestone created in the Github Issues named with the version number (e.g. "v2.2.1").

During development the version number should end in "-alpha.x" or "-beta.x", where x is an increasing number starting from 1.

Branches

  • main - the main development branch.
  • feat.foo - feature branches. these are used for longer running tasks that cannot be accomplished in one commit. once merged into master, these branches should be deleted.
  • vx.x.x - if development for a future version/milestone has begun while master is working towards a sooner release, this is the naming scheme for that branch. once merged into master, these branches should be deleted.

Tags

  • vx.x.x - commits are tagged with a final version number during release.

Issues

Issues are labelled to help track their progress within the pipeline.

  • no label - these issues have not been triaged.
  • bug - confirmed bug. aim to have a test case that reproduces the defect.
  • enhancement - contains details/discussion of a new feature. it may not yet be approved or placed into a release/milestone.
  • wontfix - closed issues that were never addressed.
  • duplicate - closed issue that is the same to another referenced issue.
  • question - purely for discussion

Management

When in doubt, find the maintainers and ask.