Skip to content
Commits on Source (2)
Expand all Hide whitespace changes
Inline Side-by-side
README.md
View file @ 1a529666
......@@ -8,7 +8,7 @@ These docs were created with [Docusaurus](https://docusaurus.io/).
1. Make sure all the dependencies for the website are installed:
In oss-website\website
In docs\website
```sh
# Install dependencies
......@@ -163,4 +163,4 @@ For more information about custom pages, click [here](https://docusaurus.io/docs
# Full Documentation
Full documentation can be found on the [website](https://docusaurus.io/).
Full documentation can be found on the [docusaurus website](https://docusaurus.io/).
docs/contributing/contributing.md
View file @ 1a529666
......@@ -3,45 +3,38 @@ id: contributing
title: Contributing
---
You can contribute to Minds with [Gitlab](https://gitlab.com/minds). Please follow the instructions below.
## Working with Minds in GitLab
## Creating an issue
The [Git/GitLab documentation](guides/git.md) explains our team workflow process and labelling guidelines. Make sure you follow these guidelines before submitting an issue or merge request.
### Feature or Bug?
## Submitting a merge request (MR)
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.
We welcome community contributions to our open-source code repositories. By signing a contributor license agreement (CLA), we ensure that the community is free to use your contributions.
### Logging a Bug
Before submitting an MR, make sure you have:
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.
1. Reviewed the [AGPLv3 license](contributing/license.md)
2. Signed the <a href="https://na3.docusign.net/Member/PowerFormSigning.aspx?PowerFormId=e9c0907f-7056-403e-9972-0caad4ced5b6&env=na3-eu1&v=2"> Contributor License Agreement (CLA)</a>
### Logging a feature request
## Submitting an issue
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.
In most cases, issues submitted by the community will either be bugs or feature requests, submitted [here](https://gitlab.com/groups/minds/-/issues). 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.
### Bug Life Cycle
- log a **bug** when something has gone wrong in the system. Before you log a bug, search through existing issues to make sure it hasn't already been reported. Use the bug template provided in GitLab and fill it out with as much information as possible - especially platform details and steps to reproduce. The more information we have, the more likely we will be able to replicate the problem and find a way to fix it.
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.
- log a **feature request** to suggest we add something that doesn't already exist on the site. Be as descriptive as possible. We welcome mock-ups and even rough sketches in notebooks if they help illustrate your idea.
### 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.
## Earn token rewards for contributing
## Priorities
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.
| 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. |
## Ways to contribute
## Progress
Looking for a project to get started? Check out:
| 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: Add a couple bounties so it's not empty? Why is i18n link broken?
## Submitting your Merge Request (MR)
- [Bounties](https://gitlab.com/groups/minds/-/issues?label_name%5B%5D=Bounty)
- [Community tasks](https://gitlab.com/groups/minds/-/issues?label_name%5B%5D=T+-+Community)
- [Nice to have](https://gitlab.com/groups/minds/-/issues?scope=all&utf8=%E2%9C%93&state=opened&label_name[]=Priority%3A%3A3%20-%20Nice%20to%20have)
- [Localization/translations](https://poeditor.com/join/project/A45VLCwD0Y)
docs/contributing/license.md
View file @ 1a529666
......@@ -3,9 +3,8 @@ id: license
title: License
---
UNLESS OTHERWISE STATED, ALL SUBMODULES AND PLUGINS ARE LICENSED UNDER THE AGPLv3 LICENSE.
## AGPLv3 LICENSE
UNLESS OTHERWISE STATED, ALL SUBMODULES AND PLUGINS ARE LICENSED UNDER THE AGPLv3 LICENSE.
GNU AFFERO GENERAL PUBLIC LICENSE
Version 3, 19 November 2007
......
docs/getting-started/installation.md
View file @ 1a529666
......@@ -5,84 +5,104 @@ title: Installation
## Repositories
Minds is split into multiple repositories:
The [Minds repository](https://gitlab.com/Minds/minds) contains multiple git submodule repositories:
- [Engine](https://github.com/Minds/engine) - Backend code & APIs
- [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
- [Engine](https://gitlab.com/Minds/engine) - Backend code & APIs
- [Front](https://gitlab.com/Minds/front) - Client side Angular2 web app
- [Sockets](https://gitlab.com/Minds/sockets) - WebSocket server for real-time communication
- [Mobile](https://gitlab.com/Minds/mobile-native) - React Native mobile apps
## Development system requirements
## Development System Requirements
- > 10GB RAM (be sure to set it in your docker settings)
- > 100GB Disk space
- [Docker Compose](https://docs.docker.com/compose/)
- 10GB RAM (also set this in _Docker > Settings > Advanced_ tab)
- 100GB Disk space
## Development Installation
### Setting up elasticsearch
### Build the Elasticsearch indexes
```
# Make sure nothing is running
docker-compose down
# Run the legacy provisioner
docker-compose up elasticsearch-legacy-provisioner
> **Linux users:**
> To get ElasticSearch 6 to run, you must make a settings change on the host machine.
> - Run ```sudo sysctl -w vm.max_map_count=262144```
> - To make it permanent, modify the variable in `/etc/sysctl.conf`
# Run the provisioner
docker-compose up elasticsearch-provisioner
```
#### Build the elasticsearch indexes
_**Linux users:** To get Elasticsearch 6 to run, you must make a settings change on the host machine:_
1. Make sure nothing is running: `docker-compose down`
2. Run the legacy provisioner: `docker-compose up elasticsearch-legacy-provisioner`
3. Run the legacy provisioner: `docker-compose up elasticsearch-provisioner`
- _Run `sudo sysctl -w vm.max_map_count=262144`_
- _To make it permanent, modify the variable in `/etc/sysctl.conf`_
### Running the stack the first time
### Running the stack for the first time
1. Run `sh init.sh` in order to install the front and engine repositories
2. Run `docker-compose up -d nginx`
3. Run `docker-compose up installer` (one time only.. initial username: minds / password: Pa$$w0rd)
4. Run `docker-compose up front-build`
5. Navigate to `http://localhost:8080`
3. Run `docker-compose up installer` (one time only... initial username: minds / password: Pa\$\$w0rd)
4. Run `docker-compose up front-build`
5. Navigate to [http://localhost:8080](http://localhost:8080)
## Troubleshooting
### Minds is already installed
- Ensure engine/settings.php does not exist and re-run `docker-compose up installer`
- Ensure **engine/settings.php** does not exist and re-run `docker-compose up installer`
### Cassandra will not boot
- Ensure thrift is enabled
- Cassandra requires at least 4GB of memory to operate. You can start Cassandra manually by running `docker-compose up cassandra`
- Ensure thrift is enabled
- Cassandra requires at least 4GB of memory to operate. You can start Cassandra manually by running `docker-compose up cassandra`
### Docker is frozen
- You might need to increase the resources allotted to Docker. To do this, go to _Docker > Preferences > Advanced_. From there, move the CPU/Memory sliders up and see if that fixes the problem
### Nuclear Option
With dockerized enviroments, it's sometimes best to start from scratch. If you want to delete your data, these steps will completely **delete** your data. You will be starting fresh.
When things aren't running smoothly in your Dockerized enviroment, sometimes it's best to start from scratch. Follow these steps to **completely delete your data** and start fresh:
```
#Remove your settings file
rm engine/settings.php
#Stop your stack
docker-compose down
#Remove your settings file
rm engine/settings.php
#Delete your data cache
rm -rf .data
#Stop your stack
docker-compose down
#Purge all volumes
docker volume prune
#Delete your data cache
rm -rf .data
```
#Purge all volumes
docker volume prune
```
That will remove all of your locally cached data. You can either rebuild the containers manually by using ```docker-compose up --build``` or delete everything to start fresh.
After you've deleted your data, you can either rebuild the containers manually by using `docker-compose up --build` or delete them:
```
# Delete all containers
docker rm $(docker ps -a -q)
# Delete all containers
docker rm $(docker ps -a -q)
```
## Production System Requirements
## Production system requirements
At this time it is not advisable to run Minds in production, however it is possible so long as you are aware of the risks.
- 3 Cassandra Nodes (Min 30gb RAM, 1TB SSD, 8 CPU)
- 1 ElasticSearch Node (Min 16GB RAM, 250GB SSD, 8 CPU) #2 nodes are recommended for failover
- 1 Docker Machine (Min 60gb RAM, 50GB SSD, 32 CPU)
\ No newline at end of file
- 1 Docker Machine (Min 60gb RAM, 50GB SSD, 32 CPU)
## Working in the development environment
Configure your settings in `settings.php`
To make your test user an admin:
Make sure you are in development mode in `settings.php`:
```php
$CONFIG->set('development_mode', true);
```
And set your test user entity's `isAdmin` flag to true.
docs/getting-started/introduction.md
View file @ 1a529666
......@@ -4,14 +4,16 @@ title: Welcome to the Minds Stack
sidebar_label: Introduction
---
Minds is a free & open-source, encrypted and reward-based social networking platform. Our [Roadmap](https://gitlab.com/groups/minds/-/roadmap), [Code](https://gitlab.com/minds/minds), [Project Management System](https://gitlab.com/groups/minds/-/boards/904772?milestone_title=sprint%3A%20Interesting%20Iguana&) and more all reside in [Gitlab](https://gitlab.com/minds).
Minds is a free & open-source, encrypted and reward-based social networking platform. Our [roadmap](https://gitlab.com/groups/minds/-/roadmap), [code](https://gitlab.com/minds/minds), [project management system](https://gitlab.com/groups/minds/-/boards), and more all reside in [GitLab](https://gitlab.com/minds).
## Security reports
Please report all security issues to [security@minds.com](mailto:security@minds.com).
## License
[AGPLv3](https://www.minds.org/docs/license.html). Please see the license file of each repository.
___Copyright Minds 2012 - 2019___
**_Copyright Minds 2012 - 2019_**
Copyright for portions of Minds are held by [Elgg](http://elgg.org), 2013 as part of the [Elgg](http://elgg.org) project. All other copyright for Minds is held by Minds, Inc.
docs/guides/architecture.md
View file @ 1a529666
......@@ -3,4 +3,19 @@ id: architecture
title: Architecture
---
> TODO
\ No newline at end of file
> TODO update this diagram
![Architecture diagram](assets/architecture-diagram.jpg "Diagram of Minds architecture")
[Click to enlarge](assets/architecture-diagram.jpg)
# Sockets
Sockets are for live interactions, such as comments, group gathering pulsators, notifications, messenger, and the jury.
Note: if you are using Docker, make sure your **JWT secret** maps to the **JWT secret** in `settings.php`. You shouldn't have to do anything if you are using Kubernetes, which automatically maps it to the helm .yaml file.
```php
$CONFIG->set('sockets-jwt-secret', '{{my-jwt-secret}}');
```
See the [README.md](https://gitlab.com/minds/sockets/blob/master/README.md) of the [Minds Sockets Server](https://gitlab.com/minds/sockets) repository for build instructions.
docs/guides/backend.md
View file @ 1a529666
This diff is collapsed.
docs/guides/deployment.md
View file @ 1a529666
......@@ -3,44 +3,48 @@ id: deployment
title: Deployment
---
Minds deploys with **[Gitlab](https://gitlab.com/minds)**, making use of Docker & Kubernetes.
Minds deploys with **[GitLab](https://gitlab.com/minds)**, making use of Docker & Kubernetes.
## Docker Containers
# Docker Containers
## FPM
### FPM
```
docker build -t minds/fpm:latest -f containers/php-fpm/Dockerfile .
```
### Runners
## Runners
```
docker build -t minds/runners:latest -f containers/php-runners/Dockerfile .
```
## Getting connected to the staging environment
# Getting connected to the staging environment
### Prerequisties
* Your AWS access keys setup in your environment
* 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,42 +76,42 @@ 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`:
```
// Twillio configuration
$CONFIG->set('twilio', [
'account_sid' => '{{ .Values.twilio.sid }}',
'auth_token' => '{{ .Values.twilio.token }}',
'from' => '{{ .Values.twilio.from }}'
]);
$CONFIG->set('twilio', [
'account_sid' => '{{ .Values.twilio.sid }}',
'auth_token' => '{{ .Values.twilio.token }}',
'from' => '{{ .Values.twilio.from }}'
]);
```
And add the values to the correponding yaml files
[Staging environment defaults](https://gitlab.com/minds/helm-charts/blob/master/minds/values.yaml)
[Production values](https://gitlab.com/minds/helm-charts/blob/master/minds/values-production.yaml)
And add the values to the correponding yaml files:
- [Staging environment defaults](https://gitlab.com/minds/helm-charts/blob/master/minds/values.yaml)
- [Production values](https://gitlab.com/minds/helm-charts/blob/master/minds/values-production.yaml)
## 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](../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:
```
helm upgrade --reuse-values --recreate-pods --set new.key='new value' --wait
helm upgrade --reuse-values --recreate-pods --set new.key='new value' --wait
{your.staging.site.subdomain} ./minds
```
So changing an **existing** configuration value is as simple as:
```console
helm upgrade --install --recreate-pods --reuse-values --set max_video_length=12600 feat-max-video-size-1506 ./minds/
```
......@@ -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
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.
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.
docs/guides/frontend.md
View file @ 1a529666
......@@ -3,24 +3,29 @@ id: frontend
title: Frontend
---
> This guide assumes that you have already installed your stack as described [here](getting-started/installation.md)
_This guide assumes that you have already [installed your stack](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 in the [front repository](https://gitlab.com/minds/front).
## Building
### Development
`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.
```console
npm run build-dev
```
Keep this running while you are working so your changes will automatically be reflected when you refresh your browser.
Note: 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 build can take up 30 minutes to complete
_Production build can take up 30 minutes to complete_
```gulp build.sass && sh build/base-locale.sh dist```
`gulp build.sass && sh build/base-locale.sh dist`
## Structure
......@@ -35,28 +40,22 @@ front
└───modules
```
## Component names
### Common
Minds follows the [BEM](http://getbem.com/naming/) naming conventions for elements and class names, with the `m-` prefix.
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/`:
eg:
```html
<m-comments__tree>
...
</m-comments__tree>
```
```html
<div class="m-comment__ownerBlock m-comment__ownerBlock--disabled">
<div class="m-commentOwnerBlock__name">
</div>
</div>
```
- **Directives**: user profile hovercard, tooltips, things related to Material design lite (slider, switch, date time picker), etc.
- **Pipes**: ... examples ...
- What else is in here...
## Components
## Naming conventions
### Component files
Components should have `.ts`, `.html` and `.scss` files with the same names.
Eg:
```
my-cool-module
└───list.component.ts
......@@ -64,8 +63,66 @@ my-cool-module
└───list.component.scss
```
### Elements and classes
Minds follows the [BEM](http://getbem.com/naming/) naming conventions for elements and class names, with the `m-` prefix. For example:
```html
<m-juryDutySession__content>
...
</m-juryDutySession__content>
```
```html
<div class="m-comment__ownerBlock m-comment__ownerBlock--disabled">
<div class="m-commentOwnerBlock__name"></div>
</div>
```
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
Minds uses [Prettier](https://prettier.io/) to enforce consistent formatting in frontend code.
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`.
## Spec tests
### Executing
#### Executing
`ng test`
#### Cypress tests
> TODO: Brian
## Styles
### Themes
A preset color palette and theme maps are defined in [themes.scss](https://gitlab.com/minds/front/blob/master/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.
#### Usage
_All_ colors should be defined using the `m-theme` mixin:
```scss
.m-comment__container {
@include m-theme() {
border: 1px solid themed($m-grey-50);
background-color: rgba(themed($m-blue-grey-200), 0.5);
box-shadow: 1px 1px 4px rgba(themed($m-black-always), 0.2);
}
&.m-comment__container--active {
font-weight: bold;
@include m-theme() {
color: themed($m-green);
}
}
}
```
`ng test`
\ No newline at end of file
If something is black or white and you want to _not_ change it 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`.
docs/guides/git.md
View file @ 1a529666
---
id: git
title: Git / Gitlab
title: Git / GitLab
---
> **NOTE:** This guide is mainly intended for the Minds development team. Please see our [contributions guide](contributing/contributing.md) for open source contributors.
## GitLab resources
## Branches vs Forks
- [Minds Group](https://gitlab.com/groups/minds)
**Branches** are preferred over forks, as they integrate with the **Review/Sandbox** environments.
- [What's happening in the current sprint](https://gitlab.com/groups/minds/-/boards) - dev team oversight
- [Issues](https://gitlab.com/groups/minds/-/issues) - all of the bite-size tasks that we want to complete
- [Merge requests](https://gitlab.com/groups/minds/-/merge_requests) - new code that hasn't been merged yet
- [Sprints](https://gitlab.com/groups/minds/-/milestones) - ongoing two-week periods of continuous development
- [Epics](https://gitlab.com/groups/minds/-/epics) - longer-term projects containing issues that share a theme
- [Roadmap](https://gitlab.com/groups/minds/-/roadmap) - visualization of epic timelines
Branch names should be no more that **20 characters** long and include one of the following prefixes:
- [Minds Repository](https://gitlab.com/minds/minds)
- [Engine](https://gitlab.com/Minds/engine) - backend code & APIs
- [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
- **fix/** *(also include the issue number)*
- **chore/** *(also include the issue number)*
- **feat/**
- **refactor/**
- **epic/** *(also include the epic number)*
## Branches vs. forks
## Merge Requests
For the Minds development team, **branches** are preferred over forks, as they integrate with the **review/sandbox** environments. Community contributors should use forks.
Ensure that you clearly explain the purpose of the merge request, and reference the original issue.
\ No newline at end of file
### Branch names
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.
## Merge requests
> If your merge request requires changes and isn't ready to be merged yet, add **WIP:** to 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:
1. Clearly explain its purpose
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._
_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 #7049._
### Using the staging environment
Once the pipeline has passed for your MR, you can test it in the staging environment by clicking the "view app" button on the MR page. If there isn't already a "view app" button, click the 4th icon on the pipeline (the row of primarily green checkmarks - the 4th one should be titled "review:"). From the dropdown that appears, select "review:start".
### QA
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.
## 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.
Be sure to tag your issue/epic/MR with as many labels as is relevant.
See the [list of labels](https://gitlab.com/groups/minds/-/labels) for comprehensive label descriptions.
### Examples
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 |
| --------------- | ------------------------------- | ----------------- | ------- | ----- | ------ | ------ | -------- | --- |
| Issue (not bug) | _Virtual reality chats_ | feat, chore, etc. | x | x | x | | | |
| Issue (bug) | _Glitch in the matrix_ | bug | x | x | x | x | x | |
| MR | _Virtual reality chats_ | any | x | x | | | x | x |
| Branch name | _virtual-reality-chats-7049_ | | | | | | | |
| Commit message | _(feat): Virtual reality chats_ | | | | | | | |
_Note: commit messages should be prefixed with "(type):" (e.g. feat, chore, bug, refactor etc.)_
## Bug lifecycle
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::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 by removing the `Type::Bug (Triage)` label and replacing it with `Type::Bug`.
docs/guides/kubernetes.md deleted 100644 → 0
View file @ c4506a45
---
id: kubernetes
title: Kubernetes
---
Minds uses the AGPLv3 License
\ No newline at end of file
docs/walk-throughs/emails.md 0 → 100644
View file @ 1a529666
---
id: emails
title: Sending emails
---
## Process overview
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/master/Core/Email/Mailer.php) does the actual sending
### Email templates
The email itself inherits from [Template.php](https://gitlab.com/minds/engine/blob/master/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/master/Components/Email/default.tpl) (which has the headers and footers).
You can also use/extend optional [EmailStyles.php](https://gitlab.com/minds/engine/blob/master/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/master/Core/Email/Partials/SuggestedChannels.php) and
[SuggestedChannels.tpl](https://gitlab.com/minds/engine/blob/master/Core/Email/Partials/Templates/SuggestedChannels.tpl) for partial usage examples.
### Testing
See email-related [CLI controllers](https://gitlab.com/minds/engine/blob/master/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' => 'my username',
'password' => 'my password',
'port' => 465
]
]);
```
Make sure runners are running so the queue can be parsed:
```console
docker-compose up runners
```
docs/walk-throughs/feature-flags.md 0 → 100644
View file @ 1a529666
---
id: feature-flags
title: Feature flags
---
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. Start by enabling a feature flag and then wrap 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
use Minds\Core\Features\Manager as FeaturesManager;
...
$this->features = new FeaturesManager;
...
if ($this->features->has('my-cool-feature')) {
// Cool backend feature for Canary users only
}
```
It works similarly in the frontend. Import `FeaturesService`, add it to the constructor, and:
```ts
if (this.featuresService.has('my-cool-feature')) {
// Cool frontend feature for Canary users only
}
```
docs/walk-throughs/infinite-scroll.md 0 → 100644
View file @ 1a529666
---
id: infinite-scroll
title: Infinite scroll
---
The following walk-through covers how to limit the amount of list items returned in a repository response, set paging tokens on Cassandra responses, and connect the requests and responses with the frontend with the help of the infinite-scroll component.
Let's say a user with a very popular channel wants to see a list of their subscribers. They have thousands of subscribers, and we only want to return 12 subscribers at a time because it would take a long time to return the entire list in one go (and their screen is only big enough to show <12 at one time subscribers anyway). As the user scrolls down their list of subscribers, we will continue populate the list by continually making requests for 12 more subscribers until they reach the end of the list.
> TODO: proofread and annotate below
### subscribers.component.ts
```ts
export class SubscribersComponent implements OnInit{
subscribers: Array<any> = [];
offset: string = '';
limit = 12;
moreData = true;
inProgress = false;
noInitResults = false;
fewerResultsThanLimit = false;
constructor(public client: Client) {}
ngOnInit() {
this.load(true);
}
load(initialLoad: boolean = false) {
if (this.inProgress) {
return;
}
this.inProgress = true;
if (initialLoad) {
this.subscribers = [];
this.moreData = true;
}
this.client
.get(`api/v2/subscribers`, { limit: this.limit, offset: this.offset })
.then((response: any) => {
// Hide infinite scroll's 'nothing more to load' notice
// if length of initial load is less than response limit
if (initialLoad && response.subscribers.length < this.limit) {
this.fewerResultsThanLimit = true;
this.moreData = false;
}
if (!response.subscribers.length) {
this.inProgress = false;
this.moreData = false;
// If no results on initial load, show notice instead of empty list
if (initialLoad) {
this.noInitResults = true;
}
return;
}
if (response['load-next']) {
this.offset = response['load-next'];
} else {
this.moreData = false;
}
this.subscribers.push(...response.subscribers);
this.inProgress = false;
})
.catch(e => {
this.moreData = false;
this.inProgress = false;
});
}
```
### subscribers.component.html
```html
<ng-container *ngFor="let subscriber of subscribers">
<div class="m-subscribers__subscriberContainer">
<div>{{subscriber.username}}</div>
</div>
</ng-container>
<div *ngIf="!fewerResultsThanLimit">
<infinite-scroll
distance="25%"
(load)="load()"
[moreData]="moreData"
[inProgress]="inProgress"
>
</infinite-scroll>
</div>
<div *ngIf="noInitResults">
<div>
You don't have any subscribers yet.
</div>
</div>
```
### api/v2/subscribers.php
```php
public function get($pages)
{
$response = [];
$limit = isset($_GET['limit']) ? $_GET['limit'] : 12;
$offset = isset($_GET['offset']) ? $_GET['offset'] : "";
$user_guid = isset($pages[0]) ? $pages[0] : Core\Session::getLoggedInUser()->guid;
$manager = Di::_()->get('Subscribers\Manager');
$opts = [
'limit'=>$limit,
'offset'=>$offset,
'referrer_guid'=>$referrer_guid
];
$subscribers = $manager->getList($opts);
$response['subscribers'] = Factory::exportable(array_values($subscribers->toArray()));
$response['load-next'] = (string) $subscribers->getPagingToken();
return Factory::response($response);
}
```
### Subscribers/Manager.php
```php
public function getList($opts = [])
{
$opts = array_merge([
'limit' => 12,
'offset' => '',
'user_guid' => null,
], $opts);
$response = $this->repository->getList($opts);
if ($opts['hydrate']) {
foreach ($response as $subscription) {
$subscriber = $this->entitiesBuilder->single($subscription->getSubscriberGuid());
$subscription->setProspect($subscriber);
}
}
return $response;
}
```
### Subscribers/Repository.php
```php
use Minds\Common\Repository\Response;
use Minds\Core\Data\Cassandra\Prepared;
use Cassandra;
class Repository
{
public function getList($opts = [])
{
$opts = array_merge([
'limit' => 12,
'offset' => '',
'user_guid' => null,
], $opts);
$response = new Response;
$cqlOpts = [];
if ($opts['limit']) {
$cqlOpts['page_size'] = (int) $opts['limit'];
}
if ($opts['offset']) {
$cqlOpts['paging_state_token'] = base64_decode($opts['offset']);
}
$query = new Prepared\Custom();
$query->query($statement, $values);
$query->setOpts($cqlOpts);
}
}
```
docs/walk-throughs/notifications.md 0 → 100644
View file @ 1a529666
---
id: notifications
title: Notifications
---
## Backend events and settings
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/master/Core/Notification/Settings/PushSettings.php):
```php
class PushSettings
{
protected $types = [
...
'videochat_complete' => true,
];
```
Also add your `notification_view` to:
- [Notification/Manager.php](https://gitlab.com/minds/engine/blob/master/Core/Notification/Manager.php) to determine which notification category it belongs to (e.g boosts, subscriptions, votes, etc.)
- [Notification/Extensions/Push.php](https://gitlab.com/minds/engine/blob/master/Core/Notification/Extensions/Push.php)
> TODO: What is Push.php? and should referrals be in there?
## Frontend template
Set up the template in [notification.component.html](https://gitlab.com/minds/front/blob/master/src/app/modules/notifications/notification.component.html):
```html
<ng-template ngSwitchCase="videochat_complete">
...
</ng-template>
```
## Testing
Make sure the notification dispatcher runner is running:
```console
docker-compose exec php-fpm php /var/www/Minds/engine/cli.php QueueRunner run --runner=NotificationDispatcher
```
docs/yarn.lock 0 → 100644
View file @ 1a529666
# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
# yarn lockfile v1
website/i18n/en.json
View file @ 1a529666
......@@ -31,13 +31,25 @@
"title": "Frontend"
},
"guides/git": {
"title": "Git / Gitlab"
},
"guides/kubernetes": {
"title": "Kubernetes"
"title": "Git / GitLab"
},
"guides/mobile": {
"title": "Mobile"
},
"walk-throughs/cookies": {
"title": "Cookies"
},
"walk-throughs/emails": {
"title": "Sending emails"
},
"walk-throughs/feature-flags": {
"title": "Feature flags"
},
"walk-throughs/infinite-scroll": {
"title": "Infinite scroll"
},
"walk-throughs/notifications": {
"title": "Notifications"
}
},
"links": {
......@@ -48,7 +60,8 @@
"categories": {
"Getting Started": "Getting Started",
"Guides": "Guides",
"Contributing": "Contributing"
"Contributing": "Contributing",
"Walk-throughs": "Walk-throughs"
}
},
"pages-strings": {
......