Skip to content

Latest commit

 

History

History
70 lines (43 loc) · 5.16 KB

CONTRIBUTING.md

File metadata and controls

70 lines (43 loc) · 5.16 KB

Contributing: what to know

There are many things to know when contributing to this repository. This document is broken into three parts to help manage the learning process: before, during, and after. The before section is preliminary information that will help form design choices when modifying the code base. The during section is the process of for changing the code and git management of those changes. The after is the process for how get the code changes merged onto the main branch of the repository.

Before

Try not use null. This always raises hackles so google "why not use null in java" and enjoy the large amount of reading. Here is an article if not interested in the google respoonse.

The concept flow through the code is single threaded down a stack. What this translates into is that classes have responsibility and should be the only class that does responsibility. An example of this is creating the SearchRequest. If every class in the system can create their own SearchRequest then some may forget to do every step necessary, like filtering based on access rights, and return results that it should not. Instead there is a SearchRequestFactory that is used by all classes that need a SearchRequest to make it. SearchRequestFactory then makes sure that all SearchRequest items conform to the global constraints. Please keep this style of conceptual flow.

What happens if new code cannot fit into the current concept flow? A refactoring of the concept flow will need to take place and all existing classes will have to be updated to the new structure. This should be resolved before any code changes take place.

The overall architecture/design is the MVC. In this insteance, the controller is the transmutation of uer inputs into the interfaces necessary for the model to fullfil the request. The model represents how the PDS data is stored internally. The view is the serialized output in its appropriate format since that is what the user sees or views.

Lastly, the code is divided into packages that very roughly group the functionality that reflect the MVC architecture/design. While they may not perfectly enforced currently, the implementation is moving in this direction:

gov.nasa.pds.

model

  • strictly autogenerated code by swagger from model/swagger.yml

api.registry

  • base package that contains
    • interfaces to break circular dependencies and improve encapsulation
    • spring-boot content.

api.registry.configuration

  • AWS, spring-boot, and swagger configuration information

api.registry.controller

  • control bidirectional transmutation between registry Java design/implementation and the swagger model (auto generated code)

api.registry.exceptions

  • all locally defined exceptions

api.registry.lexer

  • strictly autogenerated code by antlr

api.registry.model

  • supposed to be the model of how the data is stored and organized but it is much more of a hodgepodge at this time.

api.registry.search

  • required opensearch configuration for a connection and a collection of stuff that binds model needs with opensearch

api.registry.view

  • once the model has found the needed data, these unit seralize them into the request output format (header Accept value) to complete the request.

All of the interfaces in registry are a Context. What does context mean here. It represents the conceptual flow of information. Many users can access the same endpoint with differnt parameters. These context items hold the state for those individual requests just a context is normally used with program threading. They help separate those classes that need state from that which is purely functional help. In the case of the registry, very little state is needed and is easily represented with these interfaces.

During

The process of making changes are enumerated in order and should be reviewed prior to committing any changes:

  1. Create a new branch indicating the ticket being worked. For tickets of this repository should be issue_# and tickets from another repository should be repo-name_#. For instance, if the ticket being worked is in this repository and whose number is 19 then the branch name would be issue_19. Similarly if the ticket is from the repository pds-api and its number is 37, then the branch name should be pds-api_37.
  2. Make desired changes committing and pushing the branch a much as desired. In this case, the github repository should be treated as your backup; meaning, commit and push often.
  3. Create a pull request from pushes at any time but sooner the better. If there will be significant changes or time delay before all changes are ready, then mark the pull request as a draft.
  4. Automated tools will check the code for common problematic code. Address its posts at any time.

After

There are a few steps required to prepare for merging code back into the main branch:

  1. Create a pull request if have not done this already.
  2. Address all automated messages.
  3. Run all regression checks to make sure changes have re-introduced already fixed bugs.
  4. Move from draft to ready for review if in draft mode.
  5. Request review.