#Oroboros Core

Current Release: 0.2.4

Author: Brian Dayhoff

Copyright: Copyright 2016, all rights reserved.

License: MIT

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

#Interoperability and Internal Standards#

This project will make an ongoing effort to honor all applicable interoperability standards that apply and are generally accepted.

Primarily, this means following all currently accepted Psr's that directly reflect in execution at runtime. Psr's that do not reflect at runtime are considered best practices, but not enforced. As it is not possible to perfectly synchronize the release of this project with Psr's seamlessly, any newly accepted Psr's SHOULD be implemented fully before the next stable minor release.

We will also be making an effort to follow common inter-language standards that have accepted prominent useage. This applies but is not limited to the Promises/A+ Standards, which is primarily a Javascript consideration, however taking a similar approach in the PHP code with it's own internal service wrapper as well as its expected interaction with AJAX calls will make honoring this standard on the frontend significantly easier, so it should also be applied natively.

##Standard Proposals##

Additional standards not on this list should be proposed to the project author, and if they are found to be relevant, they will be scheduled for inclusion also.

##Standard Acceptance Guidelines##

Standards SHALL be SHALL NOT be accepted based on two sets of criteria. The first is whether or not the standard directly interferes with the goals of this project. The second is what it potentially adds to this system.

###Coding Style Standard Application###

These are our internal critera in regards to accepting coding style standards in general:

The standard MUST be rejected IF ANY of the following occur: * The standard MUST NOT cause the introduction of exploits that would not otherwise be there, and cannot be mitigated within the same specifications of that standard (which MAY extend other standards that acceptably address the exploits, but these MUST be explicitly referenced within the standard itself IF they do so). * The standard MUST NOT break expected programmatic operation for the sake of developer readability, AND provide is no other way to resolve this without loss of functionality or interoperability. * The standard MUST NOT require the assumption of control in any way that does not fit our architecture, AND cannot meaningfully be factored in without drastically altering our public Api or core abstraction. * The standard MUST NOT require that our code is less readable than our own standards mandate. * The standard MUST NOT inherently cause erratic behavior that cannot meaningfully be anticipated without unclear assumption. * The standard MUST NOT inherently cause corruption of expected values in any way that invalidates them when they are valid, including but not limited to character mutation during version control or external parsing, unexpected mutation of expected values, corruption of encryption or data-store records, invalidation of service requests or responses, or disruption of I/O with expected integrated external resource * The standard MUST NOT inherently require excessively tight coupling with no meaningful way to abstract this. * The standard MUST NOT inherently require the assumption of control unless invoked by the end user or 3rd party developer intentionally.

###Direct Standard Application###

Acceptance or rejection of a proposed standard will occur in the following order of considerations. Any consideration below found to fail as a result of the proposed standard will cause the standard to be rejected. It MAY be partially implemented, or it MAY be fully implemented aside from documented edge cases that can be found within this document.

####Quality of the standard:

• The standard MUST NOT be ambiguous.
• The standard MUST be in full release, and cannot be a draft, proposal, or working effort in and of itself.
• The standard MUST have significant community application in it's scope.
• The standard MUST fit into the scope of this project, and directly apply to at least some code or consideration that is a direct responsibility of this project.
• The standard MUST not be deprecated, or nearly deprecated.
• The standard MUST provide interfaces that enforce it's contract, and MAY where this is not possible, present a programming paradigm that invalidates its defined scope in an expected, documented, and recoverable way if the standard is not followed explicitly. This consideration SHALL NOT apply to purely stylistic standards that do not affect execution in any impactful way.
• The standard MUST NOT conflict with any internal standard that this system is currently implementing.
• The standard MUST NOT conflict with any existing standard that this system is currently implementing, unless it is a replacement for it entirely, and does not break operation of anything extending from the existing standard's scope.
• The standard MUST NOT inherently require explicit vendor reliance in any way that is either explicitly closed source and cannot be replicated in an open source manner, or only has one single FOR PROFIT available vendor that can be leveraged to honor the standard. This condition SHALL NOT apply to any package or development other than Oroboros core UNLESS explicitly referenced verbatim within the documentation of that software or package.

####Impact of the standard:

• The standard MUST NOT invalidate expected operation outside of its scope.
• The standard MUST NOT inherently require excessively burdensome impacts on stability.
• The standard MUST NOT inherently require excessively burdensome impacts on security.
• The standard MUST NOT inherently require excessively burdensome impacts on performance.
• The standard MUST NOT conflict with any expected and stable interoperability that the system already provides.
• The standard MUST NOT inherently require excessively burdensome impacts on code clarity.
• The standard MUST NOT require drastic alteration of the existing api, that would prevent backwards compatibility. If this applies, it MAY be flagged as a candidate for the next major release provided it meets all other criteria on this list, but SHALL NOT be implemented directly until that time.

####Considerations of proposals

• If any of the prior conditions fail, the standard MAY be considered as a guideline standard or be placed on the standards watch list until it matures.
• If any of the prior conditions fail but the overall effect of the standard is positive and congruent with our software, the standard MAY be implemented by us partially. .
• If the standard directly conflicts with existing standards or system architecture, the development team MUST investigate whether the lack of the standard has broader anti-pattern implications, or whether it will become blocking to some required functionality later on in development.

###Guideline Standard Application###

Guideline standards are standards that are not directly enforced in the codebase, and are instead applied as a best-practices approach. Where there is no direct enforcement programmatically that is possible, we will make our best effort to follow the standard, though it should not be assumed to be used universally throughout the project.

##Current Standards##

Below is a list of the standards that are currently directly invoked, considered, or otherwise applied throughout the system.

###Internal Standards###

In addition to the below general, community accepted standards, we also apply some of our own. These are described below.

It should be noted that all internal standards ONLY APPLY TO INTERNAL DEVELOPMENT.

None of these apply to 3rd party usage of this package.

These are strictly enforced in our internal development process to maximize stability and code clarity.

3rd party contributors to core development MUST follow these standards for their pull request to be accepted.

3rd party developers creating external extensions, modules, components, or other additions not designated as part of the core package SHOULD follow these, but it is generally not enforced unless required for the system to interpret your addition correctly.

3rd party developers using this package for their own private projects in a way that does not affect development of this package MAY ignore our internal standards entirely, but SHOULD consider them to be best practices in their own workflow whenever feasible for their needs.

####Internal System Architecture Standards####

(These standards are subject to update without notice throughout the alpha release phase. When the beta phase is releases, they will be considered immutable through each subsequent major release)

• All class names MUST be fully qualified. We WILL NOT accept any code with a use statement prior to the class declaration as stable, and this will need to be factored out before it makes it's way to release if it applies. For trait inclusion, use statements are required, so those applications are acceptible, provided they are not suffixed by as.
• Any useage of use ... as ... WILL NOT be accepted. These statements will be manually failed by our team when they are encountered, and a bug ticket for removal will be open if they are found to be already present. We apply this to insure that all of our internal code directly represents exactly what you are looking at, and does not require jumping back and forth to the class file heading to figure out where something goes. We will reject any pull requests that contain these, and will treat them as bugs if they are ever encountered within the existing codebase, even though they do not affect execution.
• In accordance with Psr-1, all executable or declarative files MUST only use a full opening brace <?php as their first line, or second if a shebang is also required for the file, or use the universally supported shorthand opening and closing tags: <?= ... ?>
• As an extension to the above Psr-1 standard, ALL php files MUST NOT mix a <?php opening tag within the same file that a shorthand tag (<?= ... ?>) exists, UNLESS that file is explicitly a Template, AND the opening tag is used explicitly for validation of expected values. No other edge case useage of this mix is to be considered acceptable at any time.
• As an additional extension to the above, ALL class declarations and function declarations MUST use the full <?php opening tag, and MUST NOT include a closing tag ?> at any point within their source file.
• As an additional extension to the above, ALL files that use the shorthand notation <?= ... ?> MUST be suffixed with .phtml, and MAY ONLY be used explicitly for templating.
• All files that encapsulate php within any other non-php output MUST be registered as templates AND use the .phtml file suffix.
• All global constants MUST be declared in conf/constants.php.
• All global constants MUST be overrideable by the end user, UNLESS they designate mandatory information about oroboros core, which will break the system if altered. To accomplish this, define immutable constants directly at the beginning of conf/constants.php, and declare overrideable constants by adding to the $definitions array within conf/constants.php, which is looped over at the end of the file, and declares the supplied value only if it is not already defined. This behavior allows end users to fully configure constant settings dynamically for their own environment by simply defining them before initializing the core, at which point they will be honored seamlessly, and will additionally compile into the EnvironmentApi interface, and be used natively by classes as fixed, read-only environment values.
• All files that make declarations MUST NOT also execute arbitrary code under any circumstances, UNLESS it is required for accurate declaration AND does not perform any task that persists through runtime or thereafter except declaration.
• All files that execute arbitrary code MUST be suffixed with .routine.php UNLESS that file is explicitly conf/constants.php or init.php in the root directory, which are the only two files in the system that does not follow the below conventions, and is required to work this way, and be included prior to initialization for bootloading to proceed normally. ALL other files that this consideration applies to MUST be suffixed with .routine.php AND be provided with a Routine class that manages them, OR they alternately MUST be a template AND have the .phtml suffix.
• All templates and routines MUST NOT make declarations if they are released as part of the core package, but it should be expected that end users will extend them to this effect, as this is their intended purpose.
• Default abstract classes MUST declare a class constant CLASS_TYPE, with a value inherited by direct reference to a value in \oroboros\core\abstracts\api\ClassTypeApi using the fully qualified constant name with namespace as the value. They MAY inherit this from a parent, if it is unchanged without directly declaring it, but it MUST always be present and reflect the intended class type.
• Default abstract classes MUST declare a class constant CLASS_SCOPE, with a value inherited by direct reference to a value in \oroboros\core\abstracts\api\ClassScopeApi using the fully qualified constant name with namespace as the value. They MAY inherit this from a parent, if it is unchanged without directly declaring it, but it MUST always be present and reflect the intended class scope.
• Default abstract classes MUST declare a class constant API. This value MUST be a string, and MUST resolve to a value corresponding to a valid internal Package Api Interface. They MAY inherit this from a parent, if it is unchanged without directly declaring it, but it MUST always be present and reflect the topmost Package Api Interface that the class honors directly, or satisfies a requirement of if it does not fully satisfy the api directly.
• Default abstract classes ONLY provide functionality in their own scope. They are expected to use traits or inheritance to gain any additional underlying functionality they need to accomplish their task.
• Default abstract classes MUST NOT directly implement a Api Interface, even if they honor it. Presenting the final Api is the sole task of concrete classes only.
• Default abstract classes MUST inherit their full method set from traits. This allows 3rd-party classes to remain interoperable with the system without the need for direct extension from it's classes, nor excessive integration effort by the developer desiring this functionality.
• Default abstract classes MUST only declare inheritance, trait usage, class constants, and interface implementation. They have no other task beyond this.
• Default abstract classes MUST provide ALL fixed values they use throughout their logic as a class constant listed in an Enumerated Api Interface, and MUST use only the fully qualified constant name with namespace as the value within their source where that value is needed.
• Default concrete classes MUST only extend their abstract, declare their const API = ..., and implement their Api interface. They MUST NOT provide additional functionality under any circumstances. All underlying logic is to be provided by abstraction, interfaces, and primarily traits.
• Default concrete classes MUST be prefixed by the final keyword. If you need to extend the system, extend the abstract one level beneath the concrete, but never the concrete class directly. As our concrete classes add no additional functionality, this should never cause you to miss any expected functionality.
• Default concrete classes MUST be capable of satisfying any Package Api Interface that any level of their inheritance honors These are denoted internally with the @satisfies key in the abstract (or trait) doc block comment. Any inheritance that a concrete class obtains, MUST NOT be blocking to any lower level Api interface that it's own inheritance satisfies.
• Default concrete classes MUST implement a Api Interface that declares their intended usage.
• Default concrete classes MUST provide one and only one @satisfies doc block key, which designates which Api Interfaces they are intended to directly satisfy, or alternately which prerequisite requirement interface of a Api Interface that they satisfy.
• Default concrete classes MUST provide zero or more @requires doc block keys, which designates any other Package Api Interface that MUST be represented for the class to function properly (one for each).
• Default concrete classes MUST provide zero or more @provides doc block keys, which designates any other Package Api Interface that the class satisfies indirectly, or any prerequisite requirement interface of a Api Interface that it indirectly satisfies.
• Default concrete classes MUST fail if their @requires doc block key designations are not present. This will be unit tested before release, and failed if it can proceed without any listed requirement it declares.
• Default concrete classes MUST satisfy the conditions they declare in their @satisfies doc block key. This will be unit tested before release, and failed if it cannot satisfy its declared expectation.
• Default concrete classes MUST satisfy the conditions they declare in any of their @provides doc block keys. This will be unit tested before release, and failed if the class contains any @provides keys that it cannot honor.
• Default concrete classes MUST either provide or inherit the following class constants from a class, not an interface: (CLASS_TYPE, CLASS_SCOPE, API). API MAY be false, but SHOULD be a valid Api Interface that is honored by the class. CLASS_TYPE MUST be a valid reference to a constant listed in \oroboros\core\interfaces\api\ClassTypeApi. CLASS_SCOPE MUST be a valid reference to a class constant listed in \oroboros\core\interfaces\api\ClassScopeApi. These values will be explicitly evaluated by the Codex, which will fail if they are not present, and in turn cause the class to be rejected from release until they are satisfied.
• The following class constants MUST NOT be declared in an interface of any sort: (API, CLASS_TYPE, CLASS_SCOPE). These constants are required, and MUST be overrideable, which is not possible with constants that are declared in an interface.
• Default traits provide ALL internal method functionality.
• Default traits ALWAYS follow the same inheritance structure in their use statements as their abstract class representation would use in its extends declaration.
• Default interfaces are divided into three groups: Contract Interfaces, Enumerated Api Interfaces, and Api Interfaces.
• Default Enumerated Api Interfaces ONLY declare non-colliding constants. These are used for expected values that must be present and are entirely immutable (eg: error codes, http response codes, http semantic headers, etc).
• Default Enumerated Api Interfaces MAY extend other Enumerated Api Interfaces, provided they have the same scope.
• Default Enumerated Api Interfaces MUST NOT extend Contract Interfaces or Api Interfaces under any circumstances.
• Default Api Interfaces ONLY designate what the package scope is, what it's api is, and what it accomplishes.
• Default Api Interfaces MUST NOT directly extend any other Package Api Interface under any circumstances.
• Default Api Interfaces MAY ONLY be attached to a final concrete class.
• Default Api Interfaces MAY extend both Contract Interfaces and Enumerated Api Interfaces as needed.
• Default Api Interfaces MUST be considered entirely immutable AFTER the 0.5.0 release.
• Default Api Interfaces that become blocking to ongoing development AFTER the 0.5.0 release MUST become DEPRECATED.
• Deprecated Api Interfaces MUST provide a replacement on the next immediate minor or major release, which MUST contain both the deprecated Api and ALSO the newer replacement api to be considered stable.
• Deprecated Api Interfaces MUST persist through at least one release version with a current replacement api BEFORE they may be removed.
• Deprecated Api Interfaces MUST NOT persist to the next major release. A minor release containing both a current replacement api AND the deprecated api MUST be made available prior to the next major release, and should be considered blocking to achieving the next major release.
• Deprecated Api Interfaces that cannot be suitably replaced MUST be explicitly cleared with the project owner prior to removal, and at least one minor release that designates it's full removal MUST be offered before entirely removing it.
• Default Api Interfaces MAY be moved to an extension package, provided they meet ALL of the following requirements: the core system MUST still function in their absence without dependency on them, the extension package MUST be public and stable PRIOR to removal, the extension package MUST be actively maintained, or transferred to the core team to maintain if this is not possible, and removal MUST be explicitly authorized by the project owner.
• Default Contract Interfaces MUST NOT declare class constants. Their purpose is to enforce methods only, and describe expected functionality in their scope.
• Default Contract Interfaces MUST NOT break inheritance under any circumstances.
• All ongoing development MUST proceed using errormode exception. This forces us to treat even minor warnings as fatal errors, and handle everything we encounter explicitly, which drastically improves ongoing stability.
• All Exceptions MUST extend a relevant standard PHP exception individually, or a lower level abstract Exception provided that already does. This allows 3rd party developers to write catch statements that always perform as expected, and not spend a ton of time picking through our [api documentation][docs] for acceptible use cases.
• All Exceptions MUST be handled, and MUST NOT be left to cascade uncaught to root under any circumstances, UNLESS the exception consistently breaks operation at every level of the stack all the way down to the root request originating outside of this system.
• All Exceptions that are thrown MUST provide a relevant error code as their second parameter, which MUST be a value from \oroboros\core\interfaces\api\ErrorCodeApi, or a child of this Enumerated Api Interface.
• All objects MUST handle all of their expected exceptions in their own scope. Error handling MUST NOT be deferred to a generalized error handler unless it is irrecoverable in it's own scope.
• All objects MUST escalate exceptions that break operation. The object SHOULD throw a new exception that represents its own scope when applicable, but MUST provide the prior exception as their third parameter at all times.
• All objects MUST be able to register in the Codex cleanly. If ANY object causes Codex registration to fail, it MUST be refactored so that it does not before being considered for a release.
• All documentation MUST always be available online, locally, as well as programatically at runtime.
• All online documentation MUST be versioned by release, and MUST use the standard 0.0.0 format. The release MAY be suffixed with any of (and only) the following valid suffixes (-alpha, -beta, -p####), which correspond to alpha release, beta release, and patch release, followed by the patch id number where the "#" characters are.
• All online documentation MUST be tagged as one of the following: (development, alpha, beta, pre-release, release, current, deprecated, unsupported)
• All online documentation MUST be provided for all general functions, public and private methods, and class constants. These MUST NOT be flagged as internal to avoid documentation under any circumstances.

#####The substitution principle

This allows any other object regardless of it's own inheritance to validate by implementing both the interface and corresponding trait, with little or no additional effort. Provided that no methods collide, it is an interoperable object to this system.

• Objects SHOULD universally be interchangeable with any other concrete object that honors it's expected Api.

• The means accomplishing the logic MUST be FULLY provided by a trait, which is inherited by the default object, and enforced by a corresponding interface.

• The trait MUST make any executional logic occur in a non-blocking manner provided it's corresponding api was met (exactly as if it were a class implementing that specific interface).

• The trait MUST make any executional logic occur in a non-blocking manner if it represents an expression of any standard or interface that enforces non-blocking behavior.

• The trait MUST define in its doc block comment any class constants that it requires to be set locally, as it cannot directly declare them. This includes all other traits requirements that it uses for inheritance. Traits are specifically tasked with enforcing the existence of their expected constants in their implementing class UNLESS the usage in which the constant applies specifies that it MUST be a non-blocking operation.

• The trait MUST NOT directly define any public methods beyond what is required to satisfy its corresponding interface. It MAY inherit such methods from other traits.

#####The reliability principle

This internal control paradigm allows for validation of both expected methods, as well as expected constant values through the constructor, and does not enforce direct class inheritance anywhere.

• Objects MUST be checked by interface, internally, and MUST NOT be checked by trait, or direct class inheritance that is not a native PHP class within the supported versions list for the current release of this software.

• Objects MUST NOT rely on the existence of any global value other than those explicitly declared as a dependency, or those that are always available from native PHP at runtime within the supported versions list for the current release of this software.

• Objects MUST honor a corresponding Contract Interface, which enforces the existence of methods, but does not declare constants.

• Objects that do not provide their own methods for the interface directly MUST implement both the trait and the interface.

• Objects that do not provide their expected constants MUST NOT proceed beyond instantiation at any time.

• Traits MUST NOT provide static methods that require the existence of locally defined class constants. They MAY provide additional functionality in static methods if locally defined class constants exist, but MUST NOT ERROR because of their absence.

• All interfaces MUST declare in their doc block comment which type of interface they are, using the following notation: @category contract, and supplying one of the following values: (contract, api, enumerated)

• Api Interfaces MUST declare as constant values ALL required interfaces given classes in their package are expected to honor.

• Api Interfaces MUST dedicate one constant per requirement, to be prefixed by REQUIRES_CONTRACT_, which is a string representation of the fully qualified interface name they require part of their package to have (for example const REQUIRES_CONTRACT_LOGGER_AWARE = '\\Psr\\Log\\LoggerAwareInterface';);

• Api Interfaces MUST NOT directly extent Contract Interfaces

• Api Interfaces MUST NOT use floating constant values (using global constants as their value that do not have confirmed fixed declarations).

• Api Interfaces MAY extend Enumerated Api Interfaces, but SHOULD NOT unless they need provide these values directly (like the ExceptionApi SHOULD extend the ExceptionCodeApi for example).

• Contract Interfaces MUST implement any required Enumerated Api Interfaces required to satisfy the methods they require.

• Enumerated Api Interfaces MUST NOT require methods.

• Enumerated Api Interfaces MUST NOT extend either Contract Interfaces or Api Interfaces, but MAY extend other Enumerated Api Interfaces.

#####The Scope Principle

Object scope can be enforced directly by interface, and also by the CLASS_TYPE and CLASS_SCOPE class constants. This allows for easier indexing of intended substution in the Codex. This also allows objects to establish preference when they receive a set of multiple objects that honor their expectations.

• Objects MUST declare a CLASS_TYPE, which is one of the values provided within \oroboros\core\interfaces\api\ClassTypeApi.
• Objects MUST declare a CLASS_SCOPE, which is one of the values provided within \oroboros\core\interfaces\api\ClassScopeApi.
• Objects MUST NOT effect changes outside of their declared scope and class type.
• Objects MUST implement one or more Contract Interfaces
• Objects MUST keep all of their baseline critical operations private, and parameterize input into them through protected methods that can be extended.
• Objects SHOULD keep all methods that are not inherited or part of their Contract Interface protected or private, to prevent confusion when reading their Api.
• Objects SHOULD then call the protected methods from the public methods, so that public methods are concerned with validation of request, protected methods are concerned with provision of work, and the fundamental mechanics are stable and private.
• Objects SHOULD prefix all protected and private values with an underscore, so that analysis of the object or source consistently denotes at a glance what is not externally accessible.

#####The Responsibility Principle

Objects within this system MUST always honor these expectations of responsibility.

• Objects MUST be able to provide their api upon demand.
• Objects MUST declare their dependencies.
• Objects MUST know how to access their dependencies when they are present.
• Objects MUST handle their own errors, and not escalate them unless they break operation.
• Objects MUST escalate errors appropriately that break their operation.
• Objects MUST accept interchangeable dependencies that honor their expectations.
• Objects MUST separate initialization from instantiation, but MAY call initialization within their constructor if it is appropriate to do so.
• Objects MUST be able to be re-initialized without remnant or fragmented initialization data from their previous state.
• Objects MUST NOT provide their initialization in the global scope statically if they maintain interchangeable state that affects their primary scope. The class MAY allow for initialization dependencies to be injected to replace its own, or MAY allow flags to be passed that supplement their behavior in expected ways, but MUST NOT alter valid parameters or expected output when re-initialization occurs.
• Objects MUST NOT directly allow access to variables publicly without abstracting this through either a public getter method, or the __get magic method.
• Objects MUST NOT directly allow access to setting variable values publicly without abstracting this through either a public setter method, or the __set magic method.
• Objects MAY abstract variable setting and getting so it appears direct in usage $foo->bar = 'baz';, but this MUST be processed by a method instead of directly set within the object.
• Objects MUST provide a public method to restore their state if they are stateful. Objects MAY return a copy of themselves with the correct state instead if they are immutable.
• Objects MUST enforce that their children do not break their expected operations, and account for validation and error handling where this might occur.

####Version Control Structure####

(These standards are subject to update as needed throughout our release cycle, but all contributing members will immediately be notified of changes. These standards may receive slight variation or additional requirements, but SHALL NOT be loosened at any time)

The following standards apply to the creation of stable releases that are made available to the general public.

• All merges to master may ONLY be done by the project owner, or individuals explicitly authorized by the project owner to do so.
• All merges to master AFTER the 1.0.0 release may ONLY be commits that are tagged with a stable version number.
• All merges to master prior to the 1.0.0 release MAY omit a version number if it is not applicable.
• All unstable features MUST be merged into the dev branch prior to being committed to the master branch.
• All merges to dev MUST be a merge of a feature branch, that has been locally tested prior to merging to dev.
• All merges to dev MAY be fielded by any registered internal developer.
• All merges to dev SHOULD provide an alpha, beta, or pre-release designation, UNLESS they are a fast foward of multiple merges.
• All commits on dev MUST NOT be rebased under any circumstances, UNLESS they break the branch.
• All ongoing development effort MUST be accomplished on a feature branch, which branches from the dev branch.
• All feature branches MUST be named after the feature they are primarily concerned with accomplishing.
• All feature branches MAY be sub-branched with child feature branches that deal with any blocking considerations to the primary intended feature.
• All upward merges regardless of branch, MUST provide a test suite that proves it's functionality prior to upward merge.
• All upward merges regardless of branch, MUST pass all of their unit tests prior to upward merge.
• All release versions MUST update their documentation immediately prior to being released on the dev branch or master branch.
• All release versions on the dev branch MUST have a version suffix of one of the following (-alpha, -beta, -p####, where the pound signs represent the patch id number). The version id MUST also be represented in the README.md, and in conf/constants.php, so it will properly propogate to class structure universally.
• All release versions MUST pass their CI test pipeline with a 100% success rate in order to qualify as a release.
• All commits to the master or dev branches that fail their CI testing MUST be rolled back UNLESS they occur prior to the 0.5.0 release.
• All external core extension packages broken off from the core package MUST NOT provide functionality that is required in the core package AND not supplied by the core package directly.
• All external core extension packages broken off from the core package MUST fork the core, from it's most recent stable release that contains the api to port out, and then factor out ALL of the core source EXCEPT the package being ported out, THEN provide it with a valid extension wrapper so it can be recognized by core as a core extension seamlessly.

###PSR / PHP-Fig###

For the most part, we will be following all of these standards that are in current release and apply to this project implicitly, unless noted otherwise below.

We MAY additionally choose to implement standards that are in draft status, if we find that our need demands it and the specified Psr is structured well enough to be adhered to and meet our core objectives, OR if we have a reasonable expectation that the standard in draft status SHALL eventually be released in a very close approximation to it's current public state. These cases are also mentioned below where they are known to exist.

####Psr-0 Autoloading Standard####

As this standard is officially deprecated, and was prior to the addition of the autoloader to a stable release, this standard will not be followed. Psr-4 is fully supported, and it is suggested to use that when required.

Oroboros defers this functionality to Composer, which does provide Psr-0 autoloading functionality, however dependency on Composer is slated for future removal, at which point this standard SHALL NOT be supported by this project further.

If there is sufficient end user demand, we MAY release an extension that provides backwards compatibility with this standard, but as the standard itself is deprecated, it SHALL NOT be included in the core directly.

This standard is NOT used internally whatsoever, but 3rd party useage of Psr-0 SHALL NOT be interfered with by Oroboros core.

We may retroactively decide to implement this, as it has broad use in the wild, and maximizing interoperability is a larger concern for this project than strict adherence to standards. Instead, standards are used to assist in this effort, and should never be blocking to that end.

####Psr-1 Basic Coding Standard####

Psr-1 is followed as a best practices standard, as it cannot be enforced programmatically.

There are a few minor expected deviations from this standard, which are intentionally done for additional code clarity, and these are noted below.

All other standards of Psr-1 that are not mentioned here are honored.

• Psr-1 demands that class declarations remain on one line. Oroboros does not apply this. Our reason for doing this, is that class names and interface names are always provided with their explicit full path for readability. Some of these full paths can be quite lengthy, and it is not possible to even remotely follow the Psr-2 line length maximum if these are not separated by line. This actually results in more readable class declarations than the Psr-1 standard. Our own internal standard is as follows:

  • Class declaration gets a dedicated line
  • Class inheritance gets a dedicated line
  • Class interface implementation gets one dedicated line for each interface implemented
  • All of the above are indented out four spaces from the class name declaration
  • The opening curly brace begins on its own line after whichever of the above apply, at the same vertical index as the class name declaration (consistently column 1)
  • We SHALL NOT accept contributions that apply this aspect of the Psr-1 standard in a way that reduces readability by leaving class declarations with excessively long line names. 120 character or less observations of the Psr-1 standard SHALL be accepted, if they are longer than that, they SHALL NOT be accepted without following our own standard for this case.

• Psr-1 demands that curly braces go on the following line after a declarations and conditionals. We do this in some cases and not in others, as follows:

  • This is followed for class declarations explicitly.
  • We DO NOT apply this for functions and methods.
  • We MAY apply this for conditionals, IF the conditional is particularly complex.
  • We DO NOT apply this for conditionals that are exceedingly simple, and can be easily understood by looking at them.
  • Our functions and methods place the opening curly brace one space character after the closing parenthesis of the parameter declaration, as do simple conditionals.
  • We SHALL accept contributions that favor this aspect of the Psr-1 standard over our own, but they may inadvertently be factored back to our own standard inadvertently through source formatting, and no effort will be made to prevent this.

As none of the above discrepancies affect code execution, they are not slated to change.

####Psr-2 Coding Style Guide####

Psr-2 is followed as a best practices standard, as it cannot be enforced programmatically.

We have a few discrepancies from this (and consequently also extending standards) That were intentional design choices, and cannot fully honor Psr-1 explicitly as a result of this.

The following discrepancies from this standard are present, otherwise it is followed explicitly:

• Psr-2 expects all conditions of Psr-1 to be satisfied. As we have two internal variations from this listed above that were intentional design choices, this cannot be honored due to those, which are not slated to change because they do not affect programmatic execution AND provide more readability than the Psr-1 standard.

• Psr-2 expects that no line exceed 120 characters, and the soft limit is 80 characters, but also specifies that the maximum line length cannot be enforced. For the most part we adhere to this, with one glaring exception.

  • Tags used by development libraries like ApiGen or PhpUnit, which generally look like this: @param, are exempted from this, and always have their body text on one line,regardless of length. This also applies to all other similar prefixed tags.
  • It has been found that development libraries can behave erratically when their own demands are not met, and this Psr-1 condition occasionally breaks stable operation for the sake of developer readability, which is unacceptable.
  • For this reason, this demand of Psr-1 is ignored when it interferes with expected programmatic operation in this way, but ony in regard to doc-block comment keys that are interpreted by another program.

As none of the above discrepancies affect code execution (or provide more versatility than the standard allows), they are not slated to change.

####Psr-3 Logger Interface####

Psr-3 is fully integrated, and is interoperable enough to accept any valid Psr-3 substitution.

####Psr-4 Autoloading Standard####

Psr-4 is fully integrated independently as well as through Composer compatibility, and is the systemwide standard for autoloading.

The eventual removal of Composer as a direct dependency SHALL NOT interfere with the expected operation of this standard.

It SHALL NOT accept direct substitution, as the Psr-4 standard does not provide an interface, UNLESS it can accept substitution by creating an Oroboros Extension that follows our extension guidelines.

Third parties using our sofware are under no obligation to follow this standard, and may autoload however they wish, including any combination of the functionality this software provides and any other external resource.

####Psr-5 PhpDoc Standard####

Psr-5 IS NOT integrated, because it was seemingly abandoned before official release.

IF it does reach official release, it will be integrated in a subsequent stable release of Oroboros core.

####Psr-6 Caching Interface####

Psr-6 integration is currently in priority development, and is expected to be fully integrated and seamlessly interoperable through substitution within the alpha release schedule.

####Psr-7 HTTP Message Interface####

Psr-7 is fully integrated, and is interoperable enough to accept any valid Psr-7 substitution.

However, it SHOULD be noted that our own message interface extends upon the functionality required by Psr-7 to include interoperability with cgi messages seamlessly, which will likely result in loss of functionality if substituted in that context.

####Psr-8 Huggable Interface####

Psr-5 IS NOT integrated, because it was seemingly abandoned before official release.

Despite that it IS NOT integrated, a variation of it MAY be implemented in an upcoming release anyways because its area of subject shows some promise.

IF it is integrated in some variation AND IS NOT currently under official release as a Psr standard, it SHALL NOT be enforced in our public api, AND will only be followed internally.

IF it does reach official release, it will be integrated officially, as defined in the standard in a subsequent stable release of Oroboros core.

####Psr-9 Security Advisories####

Psr-9 IS NOT currently integrated, because it has not been approved by Psr.

Some variation of this standard (possibly as it is currently defined) SHALL be integrated anyhow.

If the standard is approved by Psr, then its standard implementation will be integrated fully on a subsequent release.

####Psr-10 Security Reporting Process####

Psr-10 IS NOT currently integrated, because it has not been approved by Psr.

Some variation of this standard (possibly as it is currently defined) SHALL be integrated anyhow.

If the standard is approved by Psr, then its standard implementation will be integrated fully on a subsequent release.

####Psr-11 Container Interface####

Psr-11 is fully integrated, and is interoperable enough to accept any valid Psr-11 substitution.

It should be noted that our own internals heavily extend abstraction upon our own representation of Psr-11 containers, so low level substitution is not possible, but high level substitution is seamless.

####Psr-12 Extended Coding Style Guide####

Psr-12 is followed as a best practices standard, as it cannot be enforced programmatically.

The same mentioned discrepancies that apply to our interpretation of Psr-1 and Psr-2 also apply here.

This standard is not in official release by Psr, but will be followed otherwise aside from the listed discrepancies anyhow internally as best practices.

####Psr-13 Hypermedia Links####

Psr-13 IS NOT currently integrated, because it has not been approved by Psr.

Some variation of this standard (possibly as it is currently defined) SHALL be integrated anyhow.

If the standard is approved by Psr, then its standard implementation will be integrated fully on a subsequent release.

####Psr-14 Event Manager####

Psr-13 IS NOT currently integrated, because it has not been approved by Psr.

Some variation of this standard (possibly as it is currently defined) SHALL be integrated anyhow.

If the standard is approved by Psr, then its standard implementation will be integrated fully on a subsequent release.

Note: Our own internal architecture is laid out to support the eventual approval if this standard, as retroactively integrating it or a variant of it otherwise would be burdensome.

####Psr-15 HTTP Middleware####

Psr-13 IS NOT currently integrated, because it has not been approved by Psr.

Some variation of this standard (possibly as it is currently defined) SHALL be integrated anyhow.

If the standard is approved by Psr, then its standard implementation will be integrated fully on a subsequent release.

Note: Our own internal architecture is laid out to support the eventual approval if this standard, as retroactively integrating it or a variant of it otherwise would be burdensome.

####Psr-16 Simple Cache####

Psr-6 integration is currently planned, and will move to in priority development status after full integration of Psr-6 is confirmed to be stable. It is expected to be fully integrated and seamlessly interoperable through substitution within the alpha release schedule.

####Psr-17 HTTP Factories####

Psr-13 IS NOT currently integrated, because it has not been approved by Psr.

Some variation of this standard (possibly as it is currently defined) SHALL be integrated anyhow.

If the standard is approved by Psr, then its standard implementation will be integrated fully on a subsequent release.

Note: Some consideration must be given as to how this is expected to interact with Psr-7, and our current implementation of this, as well as the classes surrounding it and their own dependent classes.

###Other Standards###

####Zend Framework Coding Standard####

Our own internal coding style standards bear a lot of similarities to the Zend Framework Coding Standard, particularly in regards to method naming conventions.

Our standards primarily differ from these where they conflict with Psr standards, or where they mandate filestructure and naming conventions that are inconsistent with our own architecture. * Oroboros is written primarily to conform to the concept of a statement mostly representing a sentence at the high level, so that chaining is legible as an english language construct as well as a path of execution. * For this reason, we use more generalized verbage for function names, so that a statement like $account->get('email')->send($welcomeEmail, $from, $at_time); makes more linguistic sense as a readable language construct. This can often also be expressed through calls to the same effect (most apis support both) like: $account->send($welcome_email)->from($account_registration)->at($send_datetime); * Standards that enforce more explicit naming conventions are usually honored in the protected scope and below, and are usually either provided alongside the generalized api as proxies to it, but our naming convention will also support both wherever possible.

Additionally, we enforce some typecasting within function declarations ONLY for private methods, which is incompatible with the Zend coding standard. * The Zend Framework standard explicitly requires ducktyping in all instances. * The Oroboros core standard requires typecasting but only within private methods whenever it can be applied directly, as private methods cannot be called from any location other than the class they exist in, and this immediately designates that a core flaw in the code exists, which MUST be addressed by the developer immediately. This designation prevents surpressing logic errors that MUST be addressed before being considered stable. * The Oroboros core standard requires that typecasting MUST NOT be incompatible with the minimum supported PHP version (eg: only arrays and class instances for all versions that do not have a minimum supported version of PHP 7.0.0+). * The Oroboros core standard also explicitly requires ducktyping in all other instances EXCEPT the aforementioned case with private methods.

Most other conventions are observed as best practice.

These discrepancies should be expected, as while we pay a respectful nod to the fine folks at Zend, we are not attempting to recreate the Zend Framework, and consequently have our own structural considerations to adhere to. While this project has drawn some inspiration from Zend, Symphony, Laravel and several other architectures, it SHALL NOT use any of them as a mandatory dependency for our own internal core system. Oroboros is an architecture completely rolled from scratch, and did not originate as a fork or modification of any other existing MVC architecture.

####Promise/A+####

Full support for the Promise/A+ standards is planned, despite that this standard typically only applies to javascript, within the following areas: * Service wrappers that perform asynchronous calls will return a compliant Promise. * Templates that dynamically create javascript source will ALWAYS support promises, though this functionality will likely be released later as a core Extension. * Consumers of HTTP Messages that are scoped to interact with AJAX will ALWAYS be written in a way that honors Promises used on the frontend, and will ALWAYS return a Promise to their referencing class in their own scope. * Consumers of HTTP Messages that are scoped to provide inter-server REST methods will ALWAYS be written in a way that honors Promises used on the remote server, but does not inherently require them of the remote server, and will ALWAYS return a Promise to their referencing class in their own scope. * Any Extensions of Oroboros core that explicitly deal with the creation or handling of javascript source will ALWAYS provide full support for javascript Promises.

####Bash Style Guide and Coding Standards####

As this library provides a command line utility, we are making an effort to adhere to the Bash Style Guide and Coding Standards as it applies within shell scripts (.sh) supplied with this package. We could not find a better or more official best practices than this, but are open to suggestions from the bash community if it has slipped our radar.

####DOS Batch File Coding Standards####

As this library provides a command line utility, we are making an effort to adhere to the DOS Batch File Coding Standards as it applies within DOS batch files (.bat) supplied with this package. We could not find a better or more official best practices than this, but are open to suggestions from the windows community if it has slipped our radar.

Should these standards conflict with the shell scripting standards, we SHALL always give priority to the shell scripting standards, as majority useage of this platform will likely occur on a UNIX filesystem. The DOS implementation is provided as an interoperability courtesy, but MUST maintain consistent application performance and syntax with the shell version, even if that violates DOS standards. We are hoping that does not occur, but there are some known edge cases where it may. Should we encounter such an edge case that is blocking to ongoing release, we will document it thoroughly so it is known to our end users.

###Suggestions###

If you feel that we have missed any important standards, please submit them to our team as a feature request, not a bug, and we will consider them for integration. We will keep a working archive of internal decisions about all standards presented to us for inclusion, and any decision as to whether to include them or not, along with an explanation of how they do not fit our system or guidelines if they are rejected.