Skip to content

Latest commit

 

History

History
81 lines (60 loc) · 4.19 KB

CONTRIBUTING.md

File metadata and controls

81 lines (60 loc) · 4.19 KB
Raw

How to collaborate with the project

At the point of reading this, you may want to contribute to the project either because you found it interesting, or because you need to create a brand new feature as you need it. No matter what is the reason, thanks for supporting Orcha!

First things first, there are a few points that you must consider before going ahead:

  • Orcha's internals can be complex. There is a lot of magic happening behind the scenes by using the multiprocessing module.

  • Orcha is heavily based on that module, the multiprocessing one. It was conceived to be a highly parallelizable framework, therefore multiprocessing was the only option. You must be comfortable working in a parallelized environment, be aware of the concurrency and parallelization paradigms, and have some experience writing both threaded and multi-process Python applications.

  • Orcha is a framework, it is, should not be an "executable". If any of the changes you are about to introduce is an application-like feature - like do some processing for new events, perform any kind of reporting, etc - then it is better to either develop a new plugin - which can be executed - or a new pluggable.

  • Orcha is meant to be dependency-less. This means that no dependency should be added to the framework requirements. If, for any reason, a new dependency is necessary, an extensive evaluation will be performed to make sure the decision makes sense.

    Notice that there could be development dependencies, it is, dependencies that are only sed when developing Orcha. Feel free to add there any dependency you may consider it could be useful for the community to develop Orcha.

  • Contributions are always welcome, and they all will be take into account in the future development of Orcha. However, the team may consider that your contributions do not fit the project. We have the right to accept or decline any new changes.

  • Contributions should come from a pull request. Any other form of contribution will be ignored. Besides, one could be considered a contributor if an idea was given through GitHub issues, further discussed and "approved".

Please, take some time to read the statements above. Once you are comfortable with them, go ahead and follow the guidelines we give you.

Getting started

The first thing to do is to fork the project, so you can have your own copy where you can make changes. After forking it, use git clone to grab it.

You are going to need Poetry, a dependency manger that makes easier for everyone to start developing Orcha fast. Please, access Poetry's webpage and follow the instructions on how to install it.

The next step is to prepare the environment to run Orcha. Issuing the following command will install all the dependencies and prepare a virtual environment for you to work:

poetry install

You are all set! Go ahead for starting developing Orcha.

Making some changes

As an example, we are going to alter the message structure to include a new parameter that is always being sent - for example, the time the message was generated.

Orcha is divided in multiple modules:

  • bin contains the Orcha's entrypoint - the command line application.
  • exceptions contains a bunch of custom-defined exceptions, used by Orcha and its plugins.
  • ext contains all the classes, functions, and constants that are exposed to the outside (ext - external). This is basically the API used by all plugins and pluggables. Changes made here should not alter the API unless required.
  • interfaces contains a bunch of utility classes that are used either for typing purposes, for exposing some attributes to the outside, or something else.
  • lib contains the core of Orcha, where the petition is defined, the wrappers, Orcha itself and mostly the processor. This is the trickiest part of Orcha, and changes made here should be made with special care.
  • plugins defines how plugins are used by Orcha. It could contain some internal plugin that is always available when using Orcha's CLI.
  • utils is a module containing different utilities, functions or classes that are used inside or outside Orcha. Place here any code that may not fit the other modules.