You can contribute to Minds with [Gitlab](https://gitlab.com/minds). Please follow the instructions below.
You can contribute to Minds with [Gitlab](https://gitlab.com/minds). Please follow the instructions below. You may wish to familiarize yourself with the terminology and guidelines in [Git/GitLab](guides/git.md) before you get started.
> TODO add DCO/license section
## Creating an issue
### Feature or Bug?
### Feature or bug?
As a rule of thumb, log as a feature request if it does not already exist in the system and log as a bug if something has gone wrong in the system.
### Logging a Bug
### Logging a bug
For all bugs, it is important that you use the bug template when creating an issue and fill it out with as much information as possible. Try not to leave anything missing, especially platform details, and steps to reproduce - else we may have trouble replicating the issue on our end.
...
...
@@ -19,29 +21,34 @@ For all bugs, it is important that you use the bug template when creating an iss
For feature requests, until we have a template in place, you should simply try your best to be as descriptive as possible. If its a visual feature, we welcome mock-ups and even rough sketches in notebooks if they help illustrate your idea.
### Bug Life Cycle
### Bug lifecycle
Bugs generally start off in the bug triage system. The bug triage system allows us to identify and properly document incoming bugs. This means that when they are escalated from (T - Triage) to (T - Bug) label, they should contain the information necessary for a developer to complete the task.
### Labelling
If you have the required permissions, you can label a bug or feature yourself. If this is not possible, please tag a member of staff and we will tag it for you as quickly as possible. If your entry has fallen between the cracks, please post in Help and Support and we will take care of it as soon as we possibly can.
## Priorities
<!-- TODO: check if this link format works? -->
See [Labelling](guides/git.md/#labelling) to learn why and how to label your activities.
| Label | |
| ----- | ----- |
| **`Priority::0 - Urgent`** | These issues will be assigned to the currently running sprint and resolved as soon possible. |
| **`Priority::1 - High`** | To be assigned to the closest appropriate sprint or epic. |
| **`Priority::2 - Normal`** | To be allocated an epic where possible |
| **`Priority::3 - Nice to have`** | a low priority task or issue, potentially good for the community to tackle. |
| **`Priority::4 - Trivial`** | Generally for bugs or minor changes. |
If you have the required permissions, you can apply labels to a bug or feature yourself. If this is not possible, please tag a [member of staff](https://gitlab.com/groups/minds/-/group_members) in a comment on the issue page and we will tag it for you as quickly as possible.
## Progress
If your entry has fallen between the cracks, please post in the [Help & Support](https://www.minds.com/groups/profile/100000000000000681/feed) group and we will take care of it as soon as we possibly can.
| Label | |
| ----- | ----- |
| **`Status::InProgress`** | |
| **`Status::Review`** | awaiting peer review before being made live. |
| **`Status::Follow Up`** | additional information or conversations are needed before progress can be made. |
> TODO: here's how to request permissions to apply labels yourself
## Submitting your Merge Request (MR)
> TODO: acknowledge that you agree to the DCO
> TODO: what permissions does your GitLab account need, and how to get them
- Make sure you follow the activity naming and labelling guidelines in [Git/GitLab](guides/git.md)
## Earn token rewards for contributing
Developers who find bugs or contribute code or documentation may qualify for Minds token rewards. All developer contributions will first be reviewed by the Minds staff to determine if they qualify for a reward.
## Bounties?
> TODO: Bounty label isn't used anywhere... it this ever used?
@@ -14,27 +14,28 @@ The backend is split into two main areas, **Core** and **Controllers**.
**Controllers** support both *CLI* and *REST* api's. These are publically exposed as are the public interfaces for the **Core** modules/managers.
>TODO Other areas include:
>TODO Other areas include:
* Common, TODO
* Traits, TODO
```
engine
└───[Core](#core)
│ │
└───Core
│ │
│
└───[Controllers](#controllers)
│ └───[Cli](#cli)
└───Controllers
│ └───Cli
│ │ └───
│ └───[api](#api)
│ └───api
│ │ └───v1
│ │ └───v2
│
└───Common
│
└───Traits
└───Traits
```
# Core
## Abstraction design
...
...
@@ -47,8 +48,7 @@ Modules reside under the `Core` folder and must be registered in `Core\Minds.php
> TODO explain: we're going to use video chat as an example, define video chat [#creating-a-module]
> TODO add diagram here
![Module diagram](/assets/engine-module-diagram.png"Diagram of an example VideoChat module")
![Module diagram](assets/engine-module-diagram.png"Diagram of an example VideoChat module")
### Module building blocks
...
...
@@ -56,12 +56,12 @@ Modules reside under the `Core` folder and must be registered in `Core\Minds.php
#### Essential building blocks:
__**The Model**__ (e.g. `VideoChat.php`)
* the characteristics that define a single unit of whatever content your module is going to handle (e.g. a single video chat)
* you'll want to `use Minds\Traits\MagicAttributes` so you can automatically use get/set/is methods on each of your model's properties
* you'll want to `use Minds\Traits\MagicAttributes` so you can automatically use get/set/is methods on each of your model's properties
* if you'll be using an api endpoint to interact with the front end, include a `public function export() {...}` here so it can be picked up by your controller's `Factory::exportable()` function, (which transforms arrays into an exportable format)
* might include methods for calculating fields based on the repository response
>TO DO: example calculated field
__**The Manager**__ (`Manager.php`)
* interfaces with the repository
* hydrate the entities returned in the response here (if needed)
Runners are resource intensive, so you may wish to run just one, depending on what you're working on. For example:
*`docker-compose exec php-fpm php /var/www/Minds/engine/cli.php QueueRunner run --runner=NotificationDispatcher`.
*`docker-compose exec php-fpm php /var/www/Minds/engine/cli.php QueueRunner run --runner=NotificationDispatcher`
## Spec tests
Minds uses [phpspec](https://www.phpspec.net/en/stable/) and encourages test-first development.
Minds uses [phpspec](https://www.phpspec.net/en/stable/) and encourages test-first development.
Specs are highly abstracted alter-egos of your Manager, Repository and Delegate files that allow you to focus on the bare-bones concepts of what those files will eventually do when they reach their final form (so you can plan effectively before tackling practical technicalities and specifics).
...
...
@@ -246,9 +246,9 @@ bin/phpspec run
To run a specific spec file (or folder), add its name:
```console
```console
bin/phpspec run Spec/Core/VideoChats/Repository.php
```
```
To run a specific test inside of that spec file, add its starting line number:
...
...
@@ -260,7 +260,7 @@ To run a specific test inside of that spec file, add its starting line number:
Runing this command will give you deep output of the testes
```console
bin\phpspec run -vvv
bin\phpspec run -vvv
```
## Writing new tests
...
...
@@ -298,7 +298,7 @@ class ManagerSpec extends ObjectBehavior {
let(Entity$entity){
//Store a reference to the mock for reuse.
$this->entity=$entity
$this->entity=$entity
}
}
```
...
...
@@ -314,7 +314,7 @@ use Minds\Entities\Entity;
classManagerSpecextendsObjectBehavior{
publicfunctionit_should_run_test(Entity$entity){
}
}
```
...
...
@@ -335,7 +335,7 @@ willReturn simulates the response of a mocked method
### Getting to the underlying object
Sometimes, php will choke on the reflection of these mocked objects (especially when constructing other objects).
Sometimes, php will choke on the reflection of these mocked objects (especially when constructing other objects).
```php
//This will instantiate an object and still be mockable.
...
...
@@ -347,10 +347,10 @@ Sometimes, php will choke on the reflection of these mocked objects (especially
# Controllers
> TODO
## Cli
## Cli
> TODO
## api
> TODO
*`pages[0]` refers to the parameters that are sometimes added to the end of an api call
*`pages[0]` refers to the parameters that are sometimes added to the end of an api call
> This guide assumes that you have already installed your stack as described [here](getting-started/installation.md)
Minds uses [Angular 8](https://angular.io) for the frontend. Work is currently underway to introduce server side rendering with Angular Universal.
Minds uses [Angular 8](https://angular.io) for the frontend. Work is currently underway to introduce server side rendering with Angular Universal.
The source code can be found [here](https://gitlab.com/minds/front).
The source code can be found [here](https://gitlab.com/minds/front).
## Building
### Development
From the front repository,
`npm run build-dev`
Keep this running while you are editing so your changes will automatically be reflected when you refresh your browser. Note that this doesn't work for stylesheets - when working with .scss files, you'll need to run `gulp build.sass` in minds/front before you can see those changes.
Keep this running while you are editing so your changes will automatically be reflected when you refresh your browser. Note that this doesn't work for stylesheets - when working with .scss files, you'll need to run `gulp build.sass` in minds/front before you can see those changes.
> **NOTE:** This guide is mainly intended for the Minds development team. Please see our [contributions guide](contributing/contributing.md) for open source contributors.
## Branches vs Forks
## Useful links
> TODO rename this subheader?
-[Minds Group](https://gitlab.com/groups/minds)
-[What's happening in the current sprint](https://gitlab.com/groups/minds/-/boards)
-[Front](https://github.com/Minds/front) - Client side Angular2 web app
-[Sockets](https://github.com/Minds/sockets) - WebSocket server for real-time communication
-[Mobile](https://github.com/Minds/mobile-native) - React Native mobile apps
## Issues
Open an issue before creating a branch or merge request. Tag it with relevant labels such as priority level, squad, related product(s), and status. If the issue is part of an epic, associate the two by going to the epic page and adding the issue to the list.
Issues should have one of the following prefixes:
- (feat):
- (bug):
- (chore):
- (refactor):
- (code review):
> TODO what's up with code review?
> TODO ask can we git rid of the bug/fix naming convention exception and just choose one?
## Branches vs. forks
**Branches** are preferred over forks, as they integrate with the **Review/Sandbox** environments.
Branch names should be no more that **20 characters** long and include one of the following prefixes:
Branch names should be no more that **20 characters** long and include one of the following prefixes AND the related issue number (or epic number, if its an epic):
-**fix/***(also include the issue number)*
-**chore/***(also include the issue number)*
-**fix/**(use this prefix for bug issues)
-**chore/**
-**feat/**
-**refactor/**
-**epic/***(also include the epic number)*
-**epic/**
For example:
- feat/mind-meld-chats-1749
## Merge requests
Include the current sprint name at the beginning of your merge request (MR) title.
- e.g. [Sprint/RockyRaccoon](feat): Mind meld chats
> If your MR requires changes and isn't ready to be merged yet, add a 'WIP: ' at the beginning of its title.
In the description of your MR, ensure that you clearly explain its purpose and reference the original issue #.
- e.g. Allows users to chat telepathically. Users must select a checkbox in channel settings in order to opt-in. Users must be logged in and subscribed to one another in order to be eligible. Not enabled for group chats. Closes issue #1749.
## Labelling
Be sure to tag your issue/epic/MR with as many labels as is relevant. Labels help the community by providing additional, filterable information about what's currently being worked on (and by who), what are the priorities, what's going on within each developer squad, track activity related to a particular product, etc. See the [full list of labels](https://gitlab.com/groups/minds/-/labels) for more examples.
### Creating a label
> TODO is this something that any dev can/should do?
### Type
> TODO is this even used? and if not, why don't we do this instead of all of the '(feat):" stuff in titles?
### Priorities
| Label | |
| ----- | ----- |
| **`Priority::0 - Urgent`** | These issues will be assigned to the currently running sprint and resolved as soon possible. |
| **`Priority::1 - High`** | To be assigned to the closest appropriate sprint or epic. |
| **`Priority::2 - Normal`** | To be allocated an epic where possible |
| **`Priority::3 - Nice to have`** | a low priority task or issue, potentially good for the community to tackle. |
| **`Priority::4 - Trivial`** | Generally for bugs or minor changes. |
### Status
| Label | |
| ----- | ----- |
| **`Status::InProgress`** | |
| **`Status::Review`** | awaiting peer review before being made live. |
| **`Status::Follow Up`** | additional information or conversations are needed before progress can be made. |
### Product
> TODO tasks related to certain areas of subject matter e.g. Groups, Wallet, Blogs, Boost... etc. Usually aligned with modules.
### Platform
> TODO Browser, Mobile, etc...
## Merge Requests
### Triage
> TDOO
Ensure that you clearly explain the purpose of the merge request, and reference the original issue.
