Skip to content

Latest commit

 

History

History
169 lines (124 loc) · 8.18 KB

DEVELOP.md

File metadata and controls

169 lines (124 loc) · 8.18 KB

Developing

Repository Structure

File/Folder Description
Test This folder contains a C# project wich tests the rest API and Game Logic. It uses the autogenerated ReST Client.
autogen-config Contains files used for the openapi-generator
client This is a link to the autogenerated C# ReST Client
documentation Contains documentation diagrams and mardown files for the internal logic
oas Contains various formats of the documentation for the REsT API
server Contains the project for the game-server
autogen-client.bat Autogenerates the code for the client. Note: you have to sync the submodule first
autogen-server-class.sh Autogenerates a single class from the OAS file. Use this to not completely screw the server project. Usage: ./autogen-server-class.sh <CLASSNAME>
autogen-server.bat/sh Autogenerates the whole server project.
ATTENTION:** Use this ONLY when you changes A LOT in the OAS! And if you do
1. Stash your changes
2. use the script
3. discard unwanted changes
4. pop the stash
cz.json A configuration file for the CZ utility tool don't edit
sync-oas.sh Copies the new OAS into the server project. use this bevore commiting a change in the OAS

Guides

Commiting

This Project uses Conventional Commits (https://www.conventionalcommits.org/en/v1.0.0/) please do only write conventional commits.

The format for the commit messages is : <type>(<scope>): <message>

Type

  • feat Feature
  • fix A bugfix
  • perf Performance enchantment
  • docs Documentation related
  • build Changes the build/CI environment
  • style Changes in the code that do not affect the software (whitespaces, formatting)
  • test Changes to testcases
  • bump (only used internaly do not do it yourself)

Scope

the scope is optional, when you do not give a scope don't add the brackets eg:

build(gradle): add application plugin or build: add application plugin

The scope can be any one word value, and describes more closely which system is affected by the commit. You should declare your own scopes and re-use then so that software can find all commits that are related to for example javadoc

Examples:

docs(javadoc): document private variables
feat(serializer): add JSON as viable parser
fix(lang): correct typos in german translation

For more information about conventional commits visit https://www.conventionalcommits.org/en/v1.0.0/

Software

You need the software comitizen (https://commitizen-tools.github.io/commitizen/)

you can use it to do the commit messages for you (automatically format them)

but you are obligated to use it for bumping.

Creating a release (aka bumping)

After you have committed all your changes and you want to release the new version please do the following:

  1. Write testcases if they do not already exist (and only precede if they are successful)
  2. Make sure to update regarding documentations if needed
  3. Figure out the type of release:
    1. dev: The version is not done yet and only should only be used for testing purposes
    2. alpha: The version contains only complete features but the test coverage is bad
    3. beta: The version contains only complete features. All features are passing the testcases
    4. rc: The version seems to be stable but not all features are user tested
    5. release: The version is stable
  4. If it is a dev release just create a label with the name DEV-<next-version> (you can find the current version in the readme) and stop here, steps 5-8 are only for the other types
  5. important : git stash
  6. Use cz bump -pr <release-type> ( if its a release don't use -pr release and just do cz bump)
  7. Pop the stash
  8. The result
    1. All version numbers are updated (in Readme and in the Code)
    2. A tag for is created (don't forget to push it!)
    3. The Changelog updated

Changing the ReST API

The ReST API is documented using OAS, please keep up with it as it makes everything a lot easier.

We HIGHLY recommend the usage of an IDE for OAS. Specifically Stoplight, its free beautiful and fast (https://stoplight.io/studio/). Don't use the online version tho

  1. Make you changes to the Rest API in Stoplight (file location is oas/<name>.json)
    • Keep in mind how to design an API and stick to the ReST specification
  2. use the sync-oas.sh script
  3. use the autogen-server-class.sh script for each class that should have been changed
  4. Implement the changes in the server project

The implementation

In order to understand what exactly the GameRequestPipeline(GRP) is reading the regarding chapter in the diploma thesis would be very helpful.

We encourage you to JUST use the GRP. It unifies the whole Rest interface and makes implementing ReST endpoints very easy.

You don't need to do any error or exception handling! Everything is done by the GRP

Use the request pipeline like this: (For an "action endpoint" -> no body returned)

return new GameRequestPipeline()
    .Game(gameId) //selects the game with the regarding ID
    .Robot(robotId)//select the robot you want to interact with
    .Compute(c => {
        c.Game.Programming.ClearRegister(c.Robot.ID);
    })
	.Execute(); //sends a 200 response if there were no errors

Use the request pipeline like this: (For an "content endpoint" -> with return value)

return new GameRequestPipeline()
    .Game(gameId) //selects the game with the regarding ID
    .Robot(robotId)//select the robot you want to interact with
    .Compute(c => {
        c.SetResponse(c.Game.Programming.GetRegisters(c.Robot.ID));
	})
	.ExecuteSecure();//sends a 404 response if no result was produced

Structure/Namespaces

The global namespace is : Tgm.Roborally.Server

Namespace Description
Attributes autogenerated | do not touch
Authentication Contains all classes that are related to authentication and authorisation/identification
Controllers partially autogenerated Contains the classes for the rest api
Converters autogenerated | do not touch
Engine The root namespace for the game logic
Engine.Managers Managers are integral parts of the game logic
each Manager covers one aspect of the game such as
* Programming
* Upgrade Cards
* Robot Movement
Engine.Models Data Structure classes ("POO")
Engine.Phases Contains the implementations for the phases of the game
Engine.Abstraction Contains all the interfaces used for modding and creating an abstract model
Engine.Statement Contains the implementations for the different Programming Cards(aka Statements)
Filters autogenerated | do not touch
Models autogenerated | models which are used as responses in the endpoints
Edit them as you whish, just make sure they are in sync with the OAS

Important Classes

  • GameLogic
  • All Managers

Authentication

To add authentication to an Endpoint use the GameAuth attribute.

Examples:

[GameAuth(Role.ADMIN)] //only admin can access
[GameAuth(Role.ANYONE,playerSelf:true)] //admin or the player himself can acccess
[GameAuth(Role.ANYONE)] // admin or any player can access
[GameAuth(Role.PLAYER, allowConsumer: true)] //Players and consumers are allowed to access 
[GameAuth(typeof(RobotOwnerShipEnsurance))] //The robot mentioned in the path has to belong to the requesting player

RobotOwnerShipEnsurance is an implementation of OwnershipEnsurance so you can write your own implementations

The class is well documented.