Content-client NPM

opus2-client

This is the main client application for Opus2 Platform. It encompasses workspaces, files, documents, worksheets, search, document viewing and reporting.

To compile for development:

npm install

npm start

VSCode Requirements

Typescript (of course)
TSLint (the Microsoft one, not vscode-tslint). Note that tslint is being deprecated in favour of eslint by the end of 2020. We should plan to switch sometime in the middle of 2020.
Prettier. There is a prettier config file in the repository with format-on-save switched on and a few other settings. Thie should avoid whitespace changes cluttering up pull requests.

Notes

during the transitional period with Magnum, Annotate and Platform in play we will be building a variety of products from this codebase:

the worksheets page for Magnum and Annotate
the worksheets client side API for use on other magnum pages
user activity reporting
(possibly) document ingestion for Magnum

The webpack config follows the entities client project which is set up to build separate bundles for each product in the transitional phase.

Conventions

In general, follow the Basarat Typescript book including the tips section and the Styleguide.
Prefer async/await over explicit use of promises
State management: keep it isolated in its own classes, connected to react with MobX (not the listener mechanism currently present in entities-client).
Agree new dependencies with the team before introducing them. We don't want more than one way of doing any given thing.
Don't abstract too early. A bit of copy and past is fine. It is much easier to remove duplication later than it is to escape from a bad abstraction and you can't define a good abstraction from a single use case.
Rule of 3: if you need something new, just build it in in the most simple and direct way possible. If someone needs a similar thing again then just copy it. If that happens a third time, it is time to look at the three use cases and work out if they have a common core. If so, then it is time to abstract that out. Having three uses should provide enough context to define a good abstraction. If on closer analysis it turns out that the common part is not very large, then there is no point abstracting it.
The best is the enemy of the good (Voltaire). We want code that is clear, readable, maintainable and delivered on a reasonable timescale. If it doesn't follow the latest fashions that's no problem.
Avoid any, as and ! like the plague. Most of the runtime errors in Worksheets 1.0 came from these.
File naming: camelCase as Basarat says (not like the 1.0 entities-client).
(Point Free Style) is a useful guide. While we shouldn't follow it obsessively, there are good points about what makes things readable. in particular, giving functions names when technically they could be anonymous, and keeping argument lists short (as in the distance from the opening bracket to the closing one) helps the reader.

Development Process

Working from the the tasks and stories defined in Jira, the development work involves:

Creating a 'feature' branch off the master branch for the item being worked on. This can have any name, but the Jira Id ("PLAT-208" etc) is a good choice if nothing else presents itself.
Sometimes an outline proposal is required for how a feature will be implemented. This should be agreed with team before work starts. Issues that need up-front design agreement are marked as such in Jira.
Fine-grained software design and development: actually implementing the functionality. It takes up just one point in this list, but naturally this is where the majority of development effort goes.
UX review and refinement. This should work iteratively with the implementation of front-end functionality. Sometimes it makes sense to start with a detailed UX design; other times it makes sense to implement a first pass at the functionality so we can elicit any further latent requirements before focusing on the UX.
Test implementation. Again, this can precede or follow development of the functionality itself according to what works best in the situation.
Code review. The feature branch should be rebased onto the current master and a pull request made against the master branch. One or more other team members review the code and may approve it or make suggestions for modifications. Jenkins will also run the unit tests and block merging if any fail.
Once all the tests pass and the code change has been approved it is merged onto master. This can be done either by the developer or reviewer. After merging, the feature branch should be deleted from Github. (Agust 2019: the latest versions of Github can be configured to do this automatically, but we do not have that version yet so we will have to do it manually for the time being).

Git usage

Before making a pull request, rebase onto the master rather than merging. This makes the history a bit easier to follow.
Commit messages and pull requests should begin with the Jira issue id. This is used by the Github Jira integration to match up the commit with the issue so that commits and pull requests show up against issues within Jira.
Open pull requests waiting for code review should be addressed at the daily standup so we can decide who will review them with a view to getting pull requests merged within a few days at most. Small ones can often be merged much more quickly by asking a colleague to check them over and approve them if all is well.

Code organization

All the superficial concerns to do with code structure and formatting should be covered by the linting and automatic formatting.

Imports should be ordered in groups: React, react-related packages and other external packages; blueprint libraries; local dependencies; any stylesheets neeeded for external dependencies; our own stylesheets. Tslint will make you order them within each group. This structure makes it easy to see which files have UI dependencies or dependencies on other external packages.

Package structure: follow the patterns in the opus2-client project. Model code should never depend on packages that contain UI code. If a model is only needed by a particular model, it should be private to that model. If it is needed elsewhere then it should be in the common model layer.

Jira usage

Epics, stories and tasks are created as an output of the technical design phase. Stories have a more complex workflow than tasks. For tasks, the developer who handles the task should just close the issue once the task is complete. For stories, the work will require code review and testing. The issue should only be closed by the product owner or someone they delegate responsibility to and should only be closed either when all the work in the ticket is completed satisfactorily or when new tickets have been created to address any outstanding issues.

The product owner should not extend the scope of a ticket once work has started or reopen a ticket for incidental changes. These things are best handled with new tickets.

Anyone can open Bug tickets when they find defects in the product. Suggetsions for changes, improvements or new features should be fet back to the product owner and written up outside Jira. These only become Jira tickets once we definitely intend to implement them. This means that every issue in Jira should either be closed, or on a path to being closed.