Contributing with NOW Learning Management System.
Thank you for your interest in collaborating with NOW Learning Management System. (the project).
Project License.
NOW LMS is free and open source software released under the Apache Version 2 license (the license of the proyect), this means that project users can:
- Use the project for profit or not.
- Modify the project to fit theirs specific needs (clearly defining the changes made to the original project).
However, users cannot:
- Make use of the project trademarks without explicit permission.
- Require warranties of any kind; the project is distributed as is without guarantees that it may be useful for any specific purpose.
Collaborating with the project:
Ways to collaborate.
You can collaborate in different ways:
- As a developer.
- As a Quality Assurance (QA).
- Writing and improving documentation.
- Contributing ideas of new characteristics.
- Reporting bugs.
- Translating.
- Providing guidance and support to other users.
- Sharing the project with others.
Collaborating with the development of the project:
The development is cross-platform, you can use both Windows, Linux or Mac to contribute the project, to collaborate with the project you need:
Minimal Python version is: >=3.11
Technologies used:
- Backend: Flask, with a set of many libraries:
- flask-babel
- flask-caching
- flask-login
- flask-mde
- flask-reuploaded
- flask-sqlalchemy
- flask-wtf
- Frontend: Bootstrap 5.
- ORM: SQLAlchemy:
- flask-alembic
Libraries used in the project are:
Python
| Library | License | Description |
|---|---|---|
| alembic | MIT License | A database migration tool for SQLAlchemy. |
| appdirs | MIT License | A small Python module for determining appropriate platform-specific dirs. |
| argon2-cffi | MIT License | The secure Argon2 password hashing algorithm. |
| babel | BSD License | Internationalization utilities for Python. |
| bleach | Apache Software License | An easy safelist-based HTML-sanitizing tool. |
| configobj | BSD License | Config file reading, writing and validation. |
| cryptography | Apache Software License | Cryptographic recipes and primitives for Python. |
| cuid2 | MIT License | Collision-resistant unique identifier generator. |
| flask | BSD License | A simple framework for building complex web applications. |
| flask-alembic | MIT License | Flask extension for Alembic database migrations. |
| flask-babel | BSD License | Adds i18n/l10n support to Flask applications. |
| flask-caching | BSD License | Adds caching support to your Flask application. |
| flask-login | MIT License | User session management for Flask. |
| flask-mail | BSD License | Flask extension for sending email. |
| flask-mde | MIT License | Markdown editor for Flask applications. |
| flask-reuploaded | MIT License | Flexible and efficient upload handling for Flask. |
| flask-sqlalchemy | BSD License | Adds SQLAlchemy support to your Flask application. |
| flask_weasyprint | BSD License | Make PDF from HTML with Flask and WeasyPrint. |
| flask-wtf | BSD License | Simple integration of Flask and WTForms. |
| markdown | BSD License | Python implementation of Markdown. |
| memcache | Apache Software License | Pure Python memcached client. |
| pg8000 | BSD License | PostgreSQL interface library for Python. |
| pyjwt | MIT License | JSON Web Token implementation in Python. |
| python-slugify | MIT License | A Python slugify application that handles Unicode. |
| python-ulid | MIT License | Universally Unique Lexicographically Sortable Identifier. |
| qrcode | BSD License | QR Code image generator. |
| sqlalchemy | MIT License | Database Abstraction Library. |
| requests | Apache Software License | Python HTTP for Humans. |
| redis | MIT License | Python client for Redis key-value store. |
| gunicorn | MIT License | Gunicorn 'Green Unicorn' is a Python WSGI HTTP Server for UNIX. |
| waitress | ZPL 2.1 | Waitress WSGI server for production on Windows and UNIX. |
| weasyprint | BSD License | WeasyPrint converts web documents to PDF. |
| wtforms | BSD License | A flexible forms validation and rendering library. |
JavaScript
| Library | License | Description |
|---|---|---|
| alpinejs | MIT License | A rugged, minimal framework for composing JavaScript behavior. |
| bootstrap | MIT License | Sleek, intuitive, and powerful front-end framework. |
| bootstrap-icons | MIT License | Official open source SVG icon library for Bootstrap. |
| jquery | MIT License | Fast, small, and feature-rich JavaScript library. |
| reveal.js | MIT License | HTML presentation framework. |
| select2 | MIT License | Select2 is a jQuery based replacement for select boxes. |
Development is done in the branch development, once the project is released for production the branch main will contain the latest version suitable for use in production.
Getting the source code:
git clone https://github.com/bmosoluciones/now-lms.git
cd now-lms
Create a python virtual env:
python3 -m venv venv
# Linux:
source venv/bin/activate
# Windows
venv\Scripts\activate.bat
Install python deps:
python3 - m pip install -r development.txt
Compile translations:
The system is development in Spanish, compile translations to get English strings.
pybabel compile -d now_lms/translations
Install frontend tools:
cd now_lms/static/
npm install
cd ..
cd ..
Start a development server:
python dev/server.sh
Default user and password are lms-admin, default url to work with the development server will be http://127.0.0.1:8080/.
Run formating tools:
python dev/lint.sh
Run the full tests suite:
python dev/test.sh
Style Guide:
PEP8 with a maximum line length of 127 characters. Prettier for html templates.
Use semantic commits:
| Type | Scope | Example Commit Message | Purpose | SemVer Impact |
|---|---|---|---|---|
| feat | courses | feat(courses): add new enrollment flow | Introduce a new feature | MINOR (x.↑.x) |
| fix | auth | fix(auth): resolve login redirect issue | Bug fix | PATCH (x.x.↑) |
| chore | i18n | chore(i18n): add missing English translations | Maintenance / i18n updates | None (no release bump) |
| chore | deps | chore(deps): update Flask to 3.0 | Dependency update / maintenance | None / MINOR if breaking |
| docs | readme | docs(readme): update setup instructions | Documentation changes | None |
| style | ui | style(ui): fix spacing in dashboard | Code style / formatting (no logic change) | None |
| refactor | db | refactor(db): optimize course query | Code refactor without behavior change | None |
| test | blog | test(blog): add unit tests for post creation | Adding or improving tests | None |
| build | ci | build(ci): add GitHub Actions workflow | Build system / CI/CD pipeline changes | None |
| perf | cache | perf(cache): improve course load time | Performance improvements | PATCH (if non-breaking) |
| ci | pipeline | ci(pipeline): add coverage report upload | Continuous Integration related changes | None |
| revert | auth | revert(auth): undo broken login commit | Revert a previous commit | Depends (inherits type) |
| release | version | release: v1.0.0 | Release tagging | Not applicable |
Certify the origin of your contributions.
To incorporate your contributions to the project we require that you certify that the contribution or contributions are your property or that you have permission from third parties to incorporate the contribution or contributions to the project, following the developer certificate of origin.
We recommend running:
git commit -s
And an appropriate signature will be added to the commit, not included in the commits project without the corresponding Sing-Off.
Database Support
These database engines are supported and tested as part of the release validation process:
- SQLite
- PostgreSQL version 13 or superior.
- MySQL version 8 or superior.
These database engines should work but are not tested by default:
- MariaDB
- MS SQLServer
SQLite
SQLite works out of the box and if the default option if not other database engine is defined via configuration, to test NOW - LMS with SQLite just run:
python -m pytest -v --exitfirst --cov=now_lms
Postgres
To test NOW - LMS with Postgres follow this steps:
# On Fedora, Rocky Linux, Alma or RHEL:
sudo dnf install postgresql-server postgresql-contrib
sudo postgresql-setup --initdb --unit postgresql
sudo systemctl start postgresql
sudo -u postgres psql
# We use "postgresdb" as the default user, password and database name, you
# can use another database name or user credentials but be care of update the
# conection string before running the test or the development server.
postgres=# CREATE USER postgresdb WITH PASSWORD 'postgresdb';
postgres=# CREATE DATABASE postgresdb OWNER postgresdb;
postgres=# \q
Allow connet with user and password:
sudo gedit /var/lib/pgsql/data/pg_hba.conf
And edit the line host all all 127.0.0.1/32 ident and set it to host all all 127.0.0.1/32 md5
Run the test with postgres:
DATABASE_URL=postgresql://postgresdb:postgresdb@127.0.0.1:5432/postgresdb pytest -v --exitfirst --cov=now_lms
MySQL
To test NOW - LMS with MySQL follos this steps:
sudo dnf install community-mysql-server -y
sudo systemctl start mysqld
sudo mysql_secure_installation
sudo mysql -u root -p
# We use "mysqldatabase" as the default user, password and database name, you
# can use another database name or user credentials but be care of update the
# conection string before running the test or the development server.
CREATE USER 'mysqldatabase'@'localhost' IDENTIFIED BY 'mysqldatabase';
CREATE DATABASE mysqldatabase;
GRANT ALL PRIVILEGES ON mysqldatabase.* TO 'mysqldatabase'@'localhost';
FLUSH PRIVILEGES;
For the most the users, this script will work fine but if it asks you for the password, you can retrieve a temporary password from mysqld.log at /var/log/ by the given command:
sudo grep 'temporary password' /var/log/mysqld.log
Now you can test NOW - LMS with MySQL running:
DATABASE_URL=mysql://mysqldatabase:mysqldatabase@127.0.0.1:3306/mysqldatabase pytest -v --exitfirst --cov=now_lms