Skip to content

Contributing with NOW Learning Management System.

PRs Welcome GitHub top language GitHub language count GitHub contributors GitHub last commit GitHub issues GitHub pull requests

SonarCloud

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:

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.
waitress ZPL 2.1 Waitress WSGI server.
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: v0.0.1-rc1 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