@@ -13,6 +13,8 @@ We welcome community contributions to our open source code repositories. By sign
Before submitting an MR, make sure you have reviewed the [AGPLv3 license](contributing/license.md) and signed the <ahref="https://na3.docusign.net/Member/PowerFormSigning.aspx?PowerFormId=e9c0907f-7056-403e-9972-0caad4ced5b6&env=na3-eu1&v=2">Minds Contributor License Agreement</a>.
> TODO: test CLA link
### Submitting an issue
If you want to contribute but aren't ready to work with the codebase, you can submit an issue [here](https://gitlab.com/groups/minds/-/issues) instead. If you have the required permissions, you can apply labels to a bug or feature yourself. If not, tag a [member of staff](https://gitlab.com/groups/minds/-/group_members) in a comment on the issue page (or post in the [Help & Support](https://www.minds.com/groups/profile/100000000000000681/feed) group) and we will take care of it as soon as possible.
...
...
@@ -31,8 +33,9 @@ Developers who find bugs or contribute code or documentation may qualify for Min
Looking for a project to get started? Check out:
> TODO: Add a couple bounties so it's not empty? Why is i18n link broken?
* AWS_ACCESS_KEY={Your access key provided by Mark}
* AWS_SECRET_ACCESS_KEY={Your secret access key provided by Mark}
* AWS_DEFAULT_REGION=us-east-1
* Your AWS user must have access to AWS EKS
* Helm and Kubernetes installed
## Prerequisties
### Connecting
- Your AWS access keys setup in `settings.php`
-`AWS_ACCESS_KEY={Your access key provided by Mark}`
-`AWS_SECRET_ACCESS_KEY={Your secret access key provided by Mark}`
-`AWS_DEFAULT_REGION=us-east-1`
- Your AWS user must have access to AWS EKS
- Helm and Kubernetes installed
## Connecting
```console
aws eks update-kubeconfig --name=sandbox
export KUBECONFIG=$HOME/.kube/config
```
Then you should be able to see all available pods with:
```console
kubectl get pods
```
## Review Apps
# Review Apps
The review apps make use of [Helm](https://helm.sh) and [Kubernetes](https://kubernetes.io/). Our helm charts can be found [here](https://gitlab.com/minds/helm-charts) and you can inspect the review app auto deployment in our [.gitlab-ci.yml file](https://gitlab.com/minds/engine/blob/master/.gitlab-ci.yml#L52).
...
...
@@ -58,7 +62,7 @@ helm upgrade \
./helm-charts/minds
```
If you wish to use shared databases, due to resource constaints, first deploy your services and then set `deploy=false` like so:
If you wish to use shared databases, due to resource constraints, first deploy your services and then set `deploy=false` like so:
```
helm upgrade \
...
...
@@ -72,35 +76,34 @@ helm upgrade \
./helm-charts/minds
```
### Managing settings on the Review Apps
## Managing review app settings
When a pod gets deployed, [Helm charts](https://gitlab.com/minds/helm-charts) writes in the values by parsing the [configMap.yaml](https://gitlab.com/minds/helm-charts/blob/master/minds/templates/configMap.yaml).
When a pod gets deployed, [Helm charts](https://gitlab.com/minds/helm-charts) writes in the values by parsing [configMap.yaml](https://gitlab.com/minds/helm-charts/blob/master/minds/templates/configMap.yaml).
To have your values persist across builds, you must extend the settings.php script in the (configMap.yml) (https://gitlab.com/minds/helm-charts/blob/master/minds/templates/configMap.yaml)
To have your values persist across builds, you must extend the settings.php script in [configMap.yaml](https://gitlab.com/minds/helm-charts/blob/master/minds/templates/configMap.yaml).
Do not hard code the values in the configMap, reference them via *.Values.key.subkey*:
Do not hard code the values in the configMap, reference them via `.Values.key.subkey`:
Because it enables us to do something really cool, like dynamically override configuration values for your staging environment - useful for turning on your [feature flags](walk-throughs/feature-flags).
### Why so many values and templating?
Because it enables us to do something really cool, like dynamically override configuration values for your staging environment - useful for turning on your feature flags.
You can test your *local changes* and manipulate the staging environments by using the helm-charts repo. Create your branch, make your changes and then, inside your helm-charts repository branch, run:
You can test your _local changes_ and manipulate the staging environments by using the helm-charts repo. Create your branch, make your changes and then, inside your helm-charts repository branch, run:
@@ -122,20 +126,22 @@ We don't need to specify a set value here because the value doesn't exist. Howev
If you hose anything, you can always re-run the pipeline which will rebuild the pods with the latest configuration in master and start over.
## Interacting with the Staging environment
# Interacting with the staging environment
You can get access to the pods by using **kubectl**. Note, pods are read-only and ephemeral, so you can't go hacking things on the container.
Get a list of all pods
```console
kubectl get pods
```
Shell into a pod using the name from ```get pods``` (read only)
Shell into a pod using the name from `get pods` (read only)
```console
kubectl exec -it {your.staging.site.subdomain}-{pod.type}-{kubernetes-suffix} sh
```
## Production
# Production
The Minds production environment is deployed directly from the CI flow found [here](https://gitlab.com/minds/engine/blob/master/.gitlab-ci.yml#L97). Minds currently uses Docker/ECS, but plans to move to Kubernetes as soon as possible.
@@ -7,24 +7,24 @@ _This guide assumes that you have already [installed your stack](getting-started
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 in the [front repository](https://gitlab.com/minds/front).
## Building
# Building
### Development
## Development
From the front repository,
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 apply to stylesheet changes - so when you're working with .scss files, you'll need to run `gulp build.sass`in minds/front before you'll be able to 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 apply to stylesheet changes - so when you're working with .scss files, you'll need to run `gulp build.sass` before you'll be able to see those changes.
### Production
## Production
_Production build can take up 30 minutes to complete_
`gulp build.sass && sh build/base-locale.sh dist`
## Structure
# Structure
```
front
...
...
@@ -37,25 +37,19 @@ front
└───modules
```
## Component names
## Common
Minds follows the [BEM](http://getbem.com/naming/) naming conventions for elements and class names, with the `m-` prefix.
> TODO
> eg:
In most cases, new code will be stored inside subject-specific module folders. However, if you are making something that will be used throughout the site, put it in `/common` so it can be easily accessed from other modules. Some examples of the kind of things that belong in `/common`:
```html
<m-juryDutySession__content>
...
</m-juryDutySession__content>
```
-**Directives**: user profile hovercard, tooltips, things related to Material design lite (slider, switch, date time picker), etc.
If you need to add a new class to an older file that has not yet been updated to use BEM conventions, add the new class twice: once with BEM, and again with whatever legacy convention the file is currently using.
### Linting
## Linting
Minds uses [Prettier](https://prettier.io/) to enforce consistent formatting in frontend code. Before you push your MR, make sure you run `prettier --write "src/**/*.{scss,ts,html}"` (or, if possible, download a Prettier plug-in for your code editor and tell it to format the code automatically on save). Defaults are configured in `.prettierrc`.
Minds uses [Prettier](https://prettier.io/) to enforce consistent formatting in frontend code.
## Common folder
Before you push your MR, run `prettier --write "src/**/*.{scss,ts,html}"` (or, if possible, download a Prettier plug-in for your code editor and tell it to automatically format the code on save). Defaults are configured in `.prettierrc`.
> TODO
# Spec tests
In most cases, new code will be stored inside subject-specific module folders. However, if you are making something that will be used throughout the site, put it in /common so it can be easily accessed from other modules. Some examples of the kind of things that belong in /common:
### Executing
- Directives: user profile hovercard, tooltips, things related to Material design lite (slider, switch, date time picker), etc.
- Pipes: ... examples ...
- What else is in here...
`ng test`
# Styles
### Cypress tests
## Material design lite
> TODO: Brian
> TODO
# Styles
## Themes
### How does it work
A preset color palette and theme maps are defined in THEMES.SCSS. The palette contains a number of greys, blue-greys, accent colors, black, white, etc.
A preset color palette and theme maps are defined in [themes.scss](https://gitlab.com/minds/front/blob/src/stylesheets/themes.scss). The palette contains a range of greys, blue-greys, accent colors, black, white, etc.
When styling a new component, select colors that are for light theme only. Dark theme inversions will be automatically applied according to the theme map.
> TODO: User's theme preferences are stored here
### Usage
**All** colors in scss should be defined with the following syntax:
_All_ colors should be defined using the `m-theme` mixin:
Sometimes the straightforward palette mapping is too restrictive and you need a workaround to make things look the way you want them to look. Here's how to handle exception situations:
- If you want to use a shade that is in between two colors in the palette (for example, if you want something in between `$m-grey-100` and `$m-grey-200`), use rgba with themed colors: `color: rgba(themed($m-grey-200), 0.5)`
- If something is black or white and you want it to _not_ change when the theme is changed (e.g. an overlay modal background should always be black, regardless of theme), use `$m-black-always` or `$m-white-always`
- If you want to use a color that isn't on the palette and is probably only going to be used once, you can just add it to the .scss without including the theme. But this should only happen in extremely rare cases.
> TODO: If you want to go rogue and not use the map at all (for example, make something green in light mode but black in dark mode), DO THIS
If something is black or white and you want it to _not_ change when the theme is changed (e.g. an overlay modal background should always be black, regardless of theme), use `$m-black-always` or `$m-white-always`.
-[Front](https://gitlab.com/Minds/front) - client side Angular2 web app
-[Sockets](https://gitlab.com/Minds/sockets) - web socket server for real-time communication
-[Mobile](https://gitlab.com/Minds/mobile-native) - React Native mobile apps
## Branches vs. forks
For the Minds development team, **Branches** are preferred over forks, as they integrate with the **Review/Sandbox** environments. Community contributors should use forks.
For the Minds development team, **branches** are preferred over forks, as they integrate with the **review/sandbox** environments. Community contributors should use forks.
Branch names should be no more that **20 characters** long and include the related issue/epic number. For example, **virtual-reality-chats-7028**.
Branch names should be no more that **20 characters** long and include the related issue/epic number. For example, **virtual-reality-chats-7049**.
If you are working on an epic with branches in both front and engine, give both branches identical names to associate them in the sandbox.
## Issues
Open an issue before creating a branch or merge request. Tag it with relevant [labels](##Labelling) such as `Type`, `Priority`, `Status`, `Squad`, `Product` and `Platform`. If the issue is part of an epic, associate them by going to the epic page and adding the issue to its issue list.
Open an issue before creating a branch or merge request. Tag it with relevant [labels](##Labelling) such as `Type`, `Priority`, `Status`, `Squad`, `Product` and `Platform`.
If the issue is part of an epic, associate them by going to the epic page and adding the issue to its issue list.
## Merge requests
> If your merge request requires changes and isn't ready to be merged yet, add 'WIP: ' at the beginning of its title. Make sure it does not have the 'MR::Awaiting Merge' label applied.
> If your merge request requires changes and isn't ready to be merged yet, add "WIP: " at the beginning of its title. Make sure it does not have the 'MR::Awaiting Merge' label applied.
In the description of your MR, ensure that you:
...
...
@@ -42,7 +44,13 @@ In the description of your MR, ensure that you:
2. Reference the original issue # that the MR closes
3. Provide guidelines for QA testers
For example: _Allows users to chat in virtual reality. 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. To test, try to start a VR chat with/without a VR headset. Make sure you can't engage in a VR chat unless the settings checkbox is checked._
**For example**:
_Allows users to chat in virtual reality. 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_.\_
_To test, try to start a VR chat with/without a VR headset. Make sure you can't engage in a VR chat unless the settings checkbox is checked._
_Closes issue #1749._
### Using the staging environment
...
...
@@ -50,9 +58,9 @@ Once the pipeline has passed for your MR, you can test it in the staging environ
### QA
Once an MR is ready to be tested, add a "**QA**" approval rule and assign at least one approver to conduct testing. Include some testing guidelines in your MR description to point your tester in the right direction.
When an MR is ready to be tested, add a "QA" approval rule and assign at least one approver to conduct testing. Include some testing guidelines in your MR description to point your tester in the right direction.
## Labelling
## Labels
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, activity related to a particular product, etc.
...
...
@@ -62,14 +70,14 @@ See the [list of labels](https://gitlab.com/groups/minds/-/labels) for comprehen
### Examples
The table below illustrates how different naming conventions and labels apply to different issues and activities. It is not comprehensive.
The table below illustrates how different naming conventions and labels apply to different issues and activities. It is not comprehensive and team members and contributors should visit the [list of labels](https://gitlab.com/groups/minds/-/labels) and get familiar with all of the available possibilities.
| | _Example_ | Type | Product | Squad | Status | Triage | Platform | MR |
_Note: commit messages should be prefixed with "(type):" (e.g. feat, chore, bug, refactor etc.)_
...
...
@@ -78,9 +86,9 @@ _Note: commit messages should be prefixed with "(type):" (e.g. feat, chore, bug,
Bugs generally start off in the bug triage system (with a `Type::Bug (Triage)` label), which allows us to identify and properly document incoming bugs. A bug in triage can be in one of three states:
-`Triage::Questions`: the information provided in the issue's bug template was insufficient and a developer is in the process of gathering additional information from the submitting user
-`Triage::Questions`: the information provided in the issue's bug template was insufficient and a developer is in the process of gathering additional information from the submitting user
-`Triage::Review`: responsibility for the bug has been handed off from the developer in charge of incoming bug reports to a different developer
-`Triage::Unable to replicate`: we can't reproduce the bug and consequently are unable to resolve it
When the bug is replicable and the issue contains necessary information for a developer to fix it, the bug is taken out of triage - the `Type::Bug (Triage)` label is removed and replaced with `Type::Bug`.
When the bug is replicable and the issue contains necessary information for a developer to fix it, the bug is taken out of triage by removing the `Type::Bug (Triage)` label and replacing it with `Type::Bug`.
1. An event occurs (e.g. a new user joins Minds) and dispatches a message to the queue
2. The queue then dispatches an internal event
3. The internal event compiles and dispatches the email
4.[Mailer.php](https://gitlab.com/minds/engine/blob/Core/Email/Mailer.php) does the actual sending
# Email templates
The email itself inherits from [Template.php](https://gitlab.com/minds/engine/blob/Core/Email/Template.php), which builds and outputs the email. We use .tpl files that get wrapped in a general [default.tpl](https://gitlab.com/minds/engine/blob/Components/Email/default.tpl)(which has the headers and footers).
You can also use/extend optional [EmailStyles.php](https://gitlab.com/minds/engine/blob/Core/Email/EmailStyles.php) and partials (reusable snippets that get built and injected into the email) for additional control over styles. See [SuggestedChannels.php](https://gitlab.com/minds/engine/blob/Core/Email/Partials/SuggestedChannels.php) and
[SuggestedChannels.tpl](https://gitlab.com/minds/engine/blob/Core/Email/Partials/Templates/SuggestedChannels.tpl) for partial usage examples.
# Testing
See email-related [CLI controllers](https://gitlab.com/minds/engine/blob/Controllers/Cli/Email.php) for tools related to testing and building.
To actually send and test, add your own SMTP server to `settings.php`:
```php
$CONFIG->set('email',[
'smtp'=>[
'host'=>'smtp.gmail.com',
'username'=>'your username',
'password'=>'your password',
'port'=>465
]
]);
```
Make sure runners are running so the queue can be parsed:
Feature flags allow new features to be introduced to a subset of users (i.e. those in Canary mode) before they are available to all users. Do this by enabling a feature flag and then wrapping a gate around code that you want to be executed for applicable users.
# Usage
First, define and enable the flag in `settings.php`:
```php
$CONFIG->set('features',[
...
'my-cool-feature'=>true
...
])
```
In the backend:
```php
useMinds\Core\Features\ManagerasFeaturesManager;
...
$this->features=$features?:newFeaturesManager;
...
if($this->features->has('my-cool-feature')){
// Cool backend feature for Canary users only
}
```
In the frontend, import `FeaturesService`, add it to the constructor, and:
Let's say we want to create a notification to send to video chat participants after a chat has completed.
In the relevant `NotificationDelegate.php`:
```php
$this->dispatcher->trigger('notification','all',[
'to'=>[$videochat->getParticipantGuid()],
'entity'=>$hostEntity,
'from'=>$videochat->getHostGuid(),
'notification_view'=>$videochat_complete,
'params'=>[],
]);
```
Add your `notification_view` to [PushSettings.php](https://gitlab.com/minds/engine/blob/Core/Notification/Settings/PushSettings.php):
```php
classPushSettings
{
protected$types=[
...
'videochat_complete'=>true,
];
```
Also add your `notification_view` to:
-[Notification/Manager.php](https://gitlab.com/minds/engine/blob/Core/Notification/Manager.php) to determine which notification category it belongs to (e.g boosts, subscriptions, votes, etc.)
