diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md deleted file mode 100644 index a0b52dee..00000000 --- a/.github/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,56 +0,0 @@ -# Code of Conduct - -Contact: hello@extendreality.io - -## Why have a Code of Conduct? - -As contributors and maintainers of this project, we are committed to providing a friendly, safe and welcoming environment for all, regardless of age, disability, gender, nationality, race, religion, sexuality, or similar personal characteristic. - -The goal of the Code of Conduct is to specify a baseline standard of behavior so that people with different social values and communication styles can talk about Extend Reality Ltd products and repositories effectively, productively, and respectfully, even in face of disagreements. The Code of Conduct also provides a mechanism for resolving conflicts in the community when they arise. - -## Our Values - -These are the values Extend Reality Ltd developers and repository contributors should aspire to: - -* Be friendly and welcoming. -* Be patient. - * Remember that people have varying communication styles and that not everyone is using their native language. Meaning and tone can be lost in translation. -* Be thoughtful. - * Productive communication requires effort. Think about how your words will be interpreted. - * Remember that sometimes it is best to refrain entirely from commenting. -* Be respectful. - * In particular, respect differences of opinion. It is important that we resolve disagreements and differing views constructively. -* Avoid destructive behavior. - * Derailing: stay on topic; if you want to talk about something else, start a new conversation. - * Unconstructive criticism: don't merely decry the current state of affairs; offer (or at least solicit) suggestions as to how things may be improved. - * Snarking (pithy, unproductive, sniping comments). - -The following actions are explicitly forbidden: - -* Insulting, demeaning, hateful, or threatening remarks. -* Discrimination based on age, disability, gender, nationality, race, religion, sexuality, or similar personal characteristic. -* Bullying or systematic harassment. -* Unwelcome sexual advances. -* Incitement to any of these. - -## Where does the Code of Conduct apply? - -If you participate in or contribute to the Extend Reality Ltd ecosystem in any way, you are encouraged to follow the Code of Conduct while doing so. - -Explicit enforcement of the Code of Conduct applies to the official mediums operated by the Extend Reality Ltd project: - -* The official GitHub projects and code reviews. -* The official slack channels. -* The official forums. - -Other Extend Reality Ltd product and company activities (such as conferences, meetups, and other unofficial forums) are encouraged to adopt this Code of Conduct. Such groups must provide their own contact information. - -Project maintainers may remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. - -Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by emailing: hello@extendreality.io. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. **All reports will be kept confidential**. - -**The goal of the Code of Conduct is to resolve conflicts in the most harmonious way possible**. We hope that in most cases issues may be resolved through polite discussion and mutual agreement. Bannings and other forceful measures are to be employed only as a last resort. **Do not** post about the issue publicly or try to rally sentiment against a particular individual or group. - -## Acknowledgements - -This document was based on the Code of Conduct from the Elixir project. \ No newline at end of file diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md deleted file mode 100644 index f00db998..00000000 --- a/.github/CONTRIBUTING.md +++ /dev/null @@ -1,341 +0,0 @@ -# Contributing - -We are keen for developers to contribute to open source projects to keep them great! - -Whilst every effort is made to provide features that will assist a wide range of development cases, it is inevitable that we will not cater for all situations. - -Therefore, if you feel that your custom solution is generic and would assist other developers then we would love to review your contribution. - -There are however, a few guidelines that we need contributors to follow so that we can have a chance of keeping on top things. - -## Getting Started -* Make sure you have a GitHub account. -* Create a new issue on the GitHub repository, providing one does not already exist. - * Clearly describe the issue including steps to reproduce when it is a bug (fill out the issue template). - * Make sure you fill in the earliest version that you know has the issue. -* Fork the repository on GitHub. - -## Making Changes - -* Create a topic branch from where you want to base your work. - * If you're fixing a bug then target the `master` branch. - * If you're creating a new feature then target a release branch. - * Name your branch with the type of issue you are fixing; `feat`, `chore`, `docs`. - * Please avoid working directly on your master branch. -* Make sure you set the `Asset Serialization -> Mode` parameter in `Main Menu -> Edit -> Project Settings -> Editor` to `Force Text`. -* Make commits of logical units. -* Make sure your commit messages are in the proper format. - -Following the above method will ensure that all bug fixes are pushed to the `master` branch while all new features will be pushed to the relevant next release branch. This means that patch releases are much easier to do as the `master` branch will only contain bug fixes so will be used to fork into new patch releases. Then master will be re-based into the relevant next release branch so the next release also contains the updated bug fixes in the previous patch release. - -## Coding Conventions - -To ensure all code is consistent and readable, we adhere to the default coding conventions utilized in Visual Studio. The easiest first step is to auto format the code within Visual Studio with the key combination of `Ctrl + k` then `Ctrl + d` which will ensure the code is correctly formatted and indented. - -Spaces should be used instead of tabs for better readability across a number of devices (e.g. spaces look better on GitHub source view.) - -In regards to naming conventions we also adhere to the [standard .NET Framework naming convention system](https://msdn.microsoft.com/en-gb/library/x2dbyw72(v=vs.71).aspx) and use American spellings to denote classes, methods, fields, etc. - -> **Incorrect:** -``` -public Color fontColour; -``` - -> **Correct:** -``` -public Color fontColor; -``` - -All core classes should be within the relevant `Zinnia` namespace. Any required `using` lines should be within the namespace block. - -> **Incorrect:** -``` -using System; -namespace X.Y.Z -{ - public class MyClass - { - } -} -``` - -> **Correct:** -``` -namespace Zinnia.X.Y.Z -{ - using System; - - public class MyClass - { - } -} -``` - -Names of classes should always be a noun describing what the component's role is. - -> **Incorrect:** -``` -public class UpdateThing; -``` - -> **Correct:** -``` -public class ThingUpdater; -``` - -Names of methods should always be a verb describing the action that the method will carry out. Methods should also do a specific task which the name clearly highlights. Any use of the word `And`/`Or` in a method name highlights the potential issue that a method is doing too much. - -> **Incorrect:** -``` -public virtual void ContainerPosition(); -public virtual void ContainerPositionAndRotation(); -public virtual void ContainerPositionOrRotation(); -public virtual void Setup(); -``` - -> **Correct:** -``` -public virtual void UpdateContainerPosition(); -public virtual void UpdateContainerRotation(); -public virtual void SetUpContainer(); -``` - -The only deviation from the MSDN conventions are fields should start with lowercase -> `public Type myField` as this is inline with the Unity software naming convention. - -Names of fields and properties should always be an adjective with a clear understanding of what the variable is describing. It is also not necessary to repeat the type name in the variable name as it should be implicitly understood from the naming of the variable. - -> **Incorrect:** -``` -public GameObject go; -public GameObject jointGameObject; -``` - -> **Correct:** -``` -public GameObject jointContainer; -``` - -Inline variable declarations should also follow the same naming rules and be clear and concise to their purpose. They should not be abbreviated which can cause confusion whilst reading the code. - -> **Incorrect:** -``` -for (int i = 0; i < 10; i++) {} -for (int x = 0; x < 10; x++) -{ - for (int y = 0; y < 10; y++) {} -} -``` - -> **Correct:** -``` -for (int index = 0; index < 10; index++) {} -for (int containerIndex = 0; containerIndex < 10; containerIndex++) -{ - for (int clipIndex = 0; clipIndex < 10; clipIndex++) {} -} -``` - -Class methods and parameters should always denote their accessibility level using the `public` `protected` `private` keywords. Methods should also always be defined as virtual in concrete classes to allow overriding. Marking as `protected` is favored until there is good reason to make it `private`. This ensures the type is open for extension where possible. - -> **Incorrect:** -``` -void MyMethod() -``` - -> **Correct:** -``` -protected virtual void MyMethod() -``` - -The order elements are defined in a class should be as follows: - -* nested classes. -* public enums. -* serialized (public or protected/private + `[SerializeField]`) fields. -* public events. -* public properties. -* protected enums. -* protected fields. -* protected properties. -* private fields. -* private properties. -* public MonoBehaviour message methods. -* public methods. -* protected MonoBehaviour message methods. -* protected methods. -* private MonoBehaviour message methods. -* private methods. - -It is acceptable to have multiple classes defined in the same file as long as the subsequent defined classes are only used by the main class defined in the same file. However, don't nest types as it makes it harder to find and reference them. - -Where possible, the structure of the code should also flow with the accessibility level of the method or parameters. So all `public` parameters and methods should be defined first, followed by `protected` parameters and methods with `private` parameters and methods being defined last. - -Blocks of code such as conditional statements and loops should contain the block of code in braces `{ }` even if it is just one line. - -> **Incorrect:** -``` -if (this == that) { do; } -``` - -> **Correct:** -``` -if (this == that) -{ - do; -} -``` - -The exceptions to this are: - -* When defining an empty Method. -* When defining Property get/set fields that only require one line. - -> **Example:** -``` -public virtual void EmptyMethod() {} - -public Type MyType -{ - get { return _backingType; } - set - { - _backingType = value; - ConfigureMyType(_backingType); - } -} -``` - -Any method or variable references should have the most simplified name as possible, which means no additional references should be added where it's not necessary. - -> `this.transform.rotation` *is simplified to* `transform.rotation` - -> `GameObject.FindObjectsOfType` *is simplified to* `FindObjectsOfType` - -All MonoBehaviour inherited classes that implement a MonoBehaviour [Message](https://docs.unity3d.com/ScriptReference/MonoBehaviour.html) method must at least be `protected virtual` to allow any further inherited class to override and extend the methods. - -When defining arrays, it is appropriate to instantiate the array with the `System.Array.Empty()` notation instead of doing `new Array[0]`. - -All events should be UnityEvents and not C# delegates as this will automatically provide inspector helpers for attaching event listeners. - -When the actual UnityEvent is defined in code it should also be instantiated so it is not null at runtime. - -`public MyEventClass MyEventAction = new MyEventClass();` - -Public fields that are collections should favor the `System.Collections.Generic.List` data type over a simple `array` as the `List` offers helper operators for mutating the contents of the list (e.g. `Add` `Remove` `Clear`). This makes it easier when accessing the collection via another script when the contents of the collection requires changing. - -## Documentation - -All core scripts, abstractions, controls and prefabs should contain inline code documentation adhering to the [.NET Framework XML documentation comments convention](https://msdn.microsoft.com/en-us/library/b2s063f7.aspx) - -All classes, methods and UnityEvents should be documented using the XML comments and contain a 1 line `` with any additional lines included in ``. - -Public serialized parameters that appear in the inspector also require XML comments and an additional `[Tooltip("")]` which is displayed in the Unity Editor inspector panel. All parameter attributes should appear in the same attribute block and comma separated with the `Tooltip` attribute first followed by the remaining attributes in an order that makes most sense when read as a sentence. The order of documentation and parameter attributes should be: - -* XML documentation. -* Parameter attributes. - -> **Example:** -``` -/// -/// Description here. -/// -[Tooltip("Description here."), InternalSetting, SerializeField] -protected Type myType; -``` - -If a `[Header]` attribute is to be used to group fields in the Unity Inspector, then the attribute must precede the `Tooltip` attribute in the comma separated list and not be on it's own line above the XML summary as the MSDN specification dictates that attributes must annotate members. It is also advised to wrap `Header` sections using the `#region` directive to denote the block associated. The following shows a valid and invalid example: - -> **Incorrect:** -``` -[Header("My Header")] -/// -/// Description here. -/// -[Tooltip("Description here."), InternalSetting, SerializeField] -protected Type myType; -``` - -> **Correct:** -``` -#region My Header -/// -/// Description here. -/// -[Header("My Header"), Tooltip("Description here."), InternalSetting, SerializeField] -protected Type myType; -#endregion -``` - -Whenever an inherited field, method, etc. is overridden then the documentation should avoid repeating itself from the base class and instead should use the `/// ` notation instead. Despite not being needed, being explicit about inheriting the documentation simplifies checking contributions for proper documentation. - -Any references to other classes, methods or parameters should also use the `` notation within the documentation. - -## Commit Messages - -All pull request commit messages are automatically checked using [GitCop](http://gitcop.com) - this will inform you if there are any issues with your commit message and give you an opportunity to rectify any issues. - -The commit message lines should never exceed 72 characters and should be entered in the following format: - -> **Example:** -``` -(): - - - -``` - -### Type - -The type must be one of the following: - -* feat: A new feature. -* fix: A bug fix. -* docs: Documentation only changes. -* refactor: A code change that neither fixes a bug or adds a feature. -* perf: A code change that improves performance. -* test: Adding missing tests. -* chore: Changes to the build process or auxiliary tools or libraries such as documentation generation. - -### Scope - -The scope could be anything specifying the place of the commit change, such as, `Controller`, `Interaction`, `Locomotion`, etc... - -### Subject - -The subject contains succinct description of the change: - -* use the imperative, present tense: "change" not "changed" nor "changes". -* don't capitalize first letter, unless naming something, such as `Bootstrap`. -* no dot (.) at the end of the subject line. - -### Body - -Just as in the subject, use the imperative, present tense: "change" not "changed" nor "changes" The body should include the motivation for the change and contrast this with previous behaviour. References to previous commit hashes is actively encouraged if they are relevant. - -> **Incorrect commit summary:** -``` -Added feature to improve teleportation -``` -> **Incorrect commit summary:** -``` -feat(Teleport): Add feature -``` -> **Incorrect commit summary:** -``` -feat(my-teleport-feature): my feature. -``` - -> **Correct commit summary:** -``` -feat(Teleport): add fade camera option on teleport -``` - -## Submitting Changes - -* Push your changes to your topic branch in your repository. -* Submit a pull request to this repository. -* The core team will aim to look at the pull request as soon as possible and provide feedback where required. - -## Copyright Notices - -Do not include any copyright notices in any files committed to the repository. As the author of the commit you will continue to retain the copyright for the code committed but do so under the license stated in the repository as outlined in the [GitHub Terms Of Service](https://help.github.com/en/articles/github-terms-of-service#6-contributions-under-repository-license). \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md deleted file mode 100644 index 1877a19a..00000000 --- a/.github/ISSUE_TEMPLATE.md +++ /dev/null @@ -1,27 +0,0 @@ -> **NOTE:** Any issue that does not follow the below template will be immediately closed and not re-opened until the template structure is adhered to. - -### Precheck - -* Do not use the issues tracker for help or support (try Stack Overflow, etc.) -* For proposing a new feature, please check existing open and closed issues before creating a duplicate -* For bugs, do a quick search and make sure the bug has not yet been reported -* Finally, be excellent to each other, and party on! - -### Environment - -* Version of Zinnia (Github release number) (Github branch and commit hash) -* Version of the Unity software (e.g. Unity 2018.3.10f1) - -### Steps to reproduce - -Attempt to recreate the issue in a new project and provide steps to reproduce in a clear text step by step list. Include code samples, errors and stacktraces if appropriate. - -> Do not upload custom projects with custom code to demonstrate the issue. - -### Expected behavior - -Briefly describe what you expect should happen. - -### Current behavior - -Briefly describe what is actually happening. \ No newline at end of file diff --git a/.github/SUPPORT.md b/.github/SUPPORT.md deleted file mode 100644 index 03640043..00000000 --- a/.github/SUPPORT.md +++ /dev/null @@ -1 +0,0 @@ -Only submit an issue if you have a known bug or are requesting a new feature. \ No newline at end of file diff --git a/README.md b/README.md index 14f8835d..2a1ddbc9 100644 --- a/README.md +++ b/README.md @@ -12,24 +12,22 @@ Zinnia is a collection of design patterns for the [Unity] software that can be beneficial in (but not limited to) spatial computing development. - > **Requires** the Unity software version 2018.3.10f1 (or above). + > **Requires** the Unity software version `2018.3.10f1` (or above). + +## Releases + +| Branch | Version | Explanation | +|---------|--------------------------------------------------|------------------------------------| +| release | [![Release][Version-Release]][Releases] | Stable, production-ready | +| preview | [![(Pre-)Release][Version-Prerelease]][Releases] | Experimental, not production-ready | + +Releases follow the [Semantic Versioning (SemVer) system][SemVer]. ## Getting Started ### Setting up a project -* Using the Unity software version 2018.3.10f1 (or above), create a new project using the 3D Template or open an existing project. -* If the project requires Virtual Reality support: - * Ensure `Virtual Reality Supported` is checked. - * In the Unity software select `Main Menu -> Edit -> Project Settings` to open the `Project Settings` window. - * Select `Player` from the left hand menu in the `Project Settings` window. - * In the `Player` settings panel expand `XR Settings`. - * In `XR Settings` ensure the `Virtual Reality Supported` option is checked. - * Ensure the appropriate support package is installed. - * In the Unity software select `Main Menu -> Window -> Package Manager` to open the `Packages` window. - * Find the appropriate support package in the left hand menu and click on it to select it (e.g. Oculus (Standalone) or OpenVR). - * Click the `Install` button in the right hand pane of the `Packages` window for the selected support package. - * The package will now install and be available for your supported hardware. +* Using the Unity software version `2018.3.10f1` (or above), create a new project using the 3D Template or open an existing project. * Ensure the project `Scripting Runtime Version` is set to `.NET 4.x Equivalent`. * In the Unity software select `Main Menu -> Edit -> Project Settings` to open the `Project Settings` inspector. * Select `Player` from the left hand menu in the `Project Settings` window. @@ -44,7 +42,7 @@ Zinnia is a collection of design patterns for the [Unity] software that can be b * Ensure `io.extendreality` is part of `scopes`. * Add `io.extendreality.zinnia.unity` to `dependencies`, stating the latest version. - A minimal example ends up looking like this. Please note that the version `X.Y.Z` stated here is to be replaced with [the latest released version][Latest-Release]. + A minimal example ends up looking like this. Please note that the version `X.Y.Z` stated here is to be replaced with [the latest released version][Latest-Release] which is currently [![Release][Version-Release]][Releases]. ```json { "scopedRegistries": [ @@ -88,7 +86,7 @@ Because Zinnia is a package tests have to be explicitly enabled for this package } } ``` -* As noted in the [official documentation][Enable-Tests]: +* As noted in the [official Unity documentation][Enable-Tests]: > **NOTE**: You may need to re-import the package, because the test framework doesn't always immediately pick up changes to the `testables` attribute. * Within the Unity software's `Project` window expand the `Packages` node. * Right-click on the `Zinnia.Unity` child node and choose `Reimport`. @@ -99,16 +97,20 @@ Because Zinnia is a package tests have to be explicitly enabled for this package > Note: The tests are not compatible with the `Run all in player` option. -## Contributing - -We're not currently in a place where accepting contributions would be helpful. But as soon as we're ready we'll let you know! - ## Naming Inspired by the [Zinnia] genus of plants known for their colorful, long lasting flower heads and their great ease to grow from seeds. This repository, much like the Zinnia flower aims to be easy to use and allow your projects to grow and flourish into long lasting, easy to maintain solutions. > **Fun Fact:** Zinnias have been grown aboard the [International Space Station] and have demonstrated the capability to blossom in a weightless environment. +## Contributing + +Please refer to the Extend Reality [Contributing guidelines] and the [Unity project coding conventions]. + +## Code of Conduct + +Please refer to the Extend Reality [Code of Conduct]. + ## License Code released under the [MIT License][License]. @@ -127,4 +129,11 @@ These materials are not sponsored by or affiliated with Unity Technologies or it [Enable-Tests]: https://docs.unity3d.com/Manual/cus-tests.html [Latest-Release]: https://github.com/ExtendRealityLtd/Zinnia.Unity/releases/latest [Zinnia]: https://en.wikipedia.org/wiki/Zinnia -[International Space Station]: https://www.nasa.gov/image-feature/first-flower-grown-in-space-stations-veggie-facility \ No newline at end of file +[International Space Station]: https://www.nasa.gov/image-feature/first-flower-grown-in-space-stations-veggie-facility +[Releases]: ../../releases +[SemVer]: https://semver.org/ +[Version-Release]: https://img.shields.io/github/release/ExtendRealityLtd/Zinnia.Unity.svg +[Version-Prerelease]: https://img.shields.io/github/release-pre/ExtendRealityLtd/Zinnia.Unity.svg?label=pre-release&colorB=orange +[Contributing guidelines]: https://github.com/ExtendRealityLtd/.github/blob/master/CONTRIBUTING.md +[Unity project coding conventions]: https://github.com/ExtendRealityLtd/.github/blob/master/CONVENTIONS/UNITY3D.md +[Code of Conduct]: https://github.com/ExtendRealityLtd/.github/blob/master/CODE_OF_CONDUCT.md \ No newline at end of file