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.
## Working with Minds in GitLab
> TODO add DCO/license section
The [Git/GitLab documentation](guides/git.md) explains our team workflow process and labelling guidelines. Make sure you are following these guidelines before you submit an issue or merge request.
## Creating an issue
## Submitting a Merge Request (MR)
### Feature or bug?
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.
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.
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>.
### Logging a bug
### Submitting an issue
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.
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.
### Logging a feature request
In most cases, issues submitted by the community will either be bugs or feature requests.
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.
- 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 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.
### Bug lifecycle
- 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.
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
<!-- TODO: check if this link format works? -->
See [Labelling](guides/git.md/#labelling) to learn why and how to label your activities.
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.
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.
> 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
### 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?
> 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`
#### Build the elasticsearch indexes
### Build the elasticsearch indexes
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`
_**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`_
### Running the stack 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)
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`
...
...
@@ -49,12 +46,17 @@ Minds is split into multiple repositories:
- 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
...
...
@@ -68,15 +70,13 @@ With dockerized enviroments, it's sometimes best to start from scratch. If you w
#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)
```
## Production System Requirements
...
...
@@ -85,4 +85,11 @@ At this time it is not advisable to run Minds in production, however it is possi
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).
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
...
...
@@ -74,7 +74,7 @@ helm upgrade \
### Managing settings on the Review Apps
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 the [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)
...
...
@@ -103,7 +103,7 @@ Because it enables us to do something really cool, like dynamically override con
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:
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
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.
> 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.
...
...
@@ -12,16 +12,17 @@ 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 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.
### 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
...
...
@@ -40,16 +41,17 @@ front
Minds follows the [BEM](http://getbem.com/naming/) naming conventions for elements and class names, with the `m-` prefix.
Components should have `.ts`, `.html` and `.scss` files with the same names.
Eg:
```
my-cool-module
└───list.component.ts
...
...
@@ -69,4 +72,61 @@ my-cool-module
### Executing
`ng test`
\ No newline at end of file
`ng test`
### Cypress tests
> TODO
### 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`.
## Common folder
> TODO
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:
- Directives: user profile hovercard, tooltips, things related to Material design lite (slider, switch, date time picker), etc.
- Pipes: ... examples ...
- What else is in here...
# Styles
## Material design lite
> TODO
## 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.
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:
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
> **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
## 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://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
## Branches vs. forks
## Issues
For the Minds development team, **Branches** are preferred over forks, as they integrate with the **Review/Sandbox** environments. Community contributors should use forks.
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.
Branch names should be no more that **20 characters** long and include the related issue/epic number. For example, **virtual-reality-chats-7028**.
Issues should have one of the following prefixes:
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.
- (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?
## Issues
## Branches vs. forks
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.
**Branches** are preferred over forks, as they integrate with the **Review/Sandbox** environments.
## Merge requests
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):
> 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.
-**fix/** (use this prefix for bug issues)
-**chore/**
-**feat/**
-**refactor/**
-**epic/**
In the description of your MR, ensure that you:
For example:
- feat/mind-meld-chats-1749
1. Clearly explain its purpose
2. Reference the original issue # that the MR closes
3. Provide guidelines for QA testers
## Merge requests
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._
Include the current sprint name at the beginning of your merge request (MR) title.
- e.g. [Sprint/RockyRaccoon](feat): Mind meld chats
### Using the staging environment
> If your MR requires changes and isn't ready to be merged yet, add a 'WIP: ' at the beginning of its title.
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".
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.
### 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.
## 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?
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.
### Type
> TODO is this even used? and if not, why don't we do this instead of all of the '(feat):" stuff in titles?
See the [list of labels](https://gitlab.com/groups/minds/-/labels) for comprehensive label descriptions.
### Examples
### Priorities
The table below illustrates how different naming conventions and labels apply to different issues and activities. It is not comprehensive.
| 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. |
| | _Example_ | Type | Product | Squad | Status | Triage | Platform | MR |
_Note: commit messages should be prefixed with "(type):" (e.g. feat, chore, bug, refactor etc.)_
| 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. |
## Bug lifecycle
### Product
> TODO tasks related to certain areas of subject matter e.g. Groups, Wallet, Blogs, Boost... etc. Usually aligned with modules.
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:
### Platform
> TODO Browser, Mobile, etc...
-`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
> TDOO
-`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
### MR: ...
> TODO
\ No newline at end of file
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`.
