Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
213 lines (156 loc) · 5.22 KB

CONTRIBUTING.md

File metadata and controls

213 lines (156 loc) · 5.22 KB

Contributing

Recommended setup

Docker Web Server with Nginx, PHP, and Node

For a simple local development environment running in a docker container, you will need:

Clone the repository and navigate to the project directory in terminal. Inside the project directory, use 'docker-compose' with the '-d' flag to run the website in a container.

cd ./dev && docker-compose up -d

Then navigate to localhost:8000 to view the site.

Lastly, to bring down the container/local site, run this command:

docker-compose down


Manual setup

Simple PHP Server

For a simple local development environment running on PHP, you will need:

GNU/Linux Based Operating Systems

First, install Node.js (18.x recommended) from Nodesource.

If you are on an unsupported version of elementary OS—i.e. during development of a new version—you may need to download the provided installation script, modify it first to map elementaryOS and the version codename to Ubuntu and its equivalent codename, then chmod +x the script and run it as root.

The rest can be most easily installed from Terminal on elementary OS 7.x (Ubuntu 22.04) or 8.x (Ubuntu 24.04):

sudo apt install php-cli php-curl php-intl php-json php-mbstring php-xml composer

Then inside the project directory, use npm to build

npm ci && npm run build

and npm to run the server. Navigate to localhost:8000 to view the site.

npm run start

If you are working on CSS and would like an easier time developing, you can run the npx gulp watch command. This will watch for any CSS and image changes, and rebuild on the fly.

macOS

First, make sure you have your system updated.

Second, install Node.js (18.x recommended) from Nodejs.org.

Then follow these directions from your favorite shell:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install php composer
npm ci
cd _backend
composer up
cd ../
npm run build && npm run start

Once finished, open a browser and navigate to http://localhost:8000. Enjoy!

NOTE: The version of PHP shipped via brew has all modules enabled by default.

Nginx Web Server

For a full web-server environment, which includes more redirect and permissions you may find useful, you will need:

  • Everything required for "Simple PHP Server" (above)
  • The latest stable version of Nginx
  • php8.1-fpm

Then, we need to configure Nginx. To start, open up a configuration file in Nano.

sudo nano /etc/nginx/sites-enabled/mvp.conf

Then, paste in required configuration in, modifying the root, include and error_log paths.

server {
    listen 80;
    server_name mvp.localtest.me;
    root /path/to/mvp;
    include /path/to/mvp/nginx.conf;
    error_log /path/to/error.log;
}

You can test the configuration with Nginx.

sudo nginx -t

Now we just need to restart the service.

sudo service nginx restart

Then we need to build the static assets.

npm ci && npm run build

Finally, navigate to mvp.localtest.me

Code Style

  • Four space indentation
  • Remove trailing whitespaces and add an empty line at the end of each file
  • Compatibility with the latest versions of popular browsers (chrome, firefox, safari, edge, midori)

PHP

  • include templates, not require or _once
  • Use full PHP tags, not short ones
  • Don't close PHP tags on PHP only files
  • Correctly format assignments for readability
<?php
    require_once __DIR__.'/_backend/preload.php';
    $page['title'] = 'HTML Safe Title';
    include $template['header'];

    $foo        = bar($para, $param);
    $second_foo = 42;
    $third_foo  = 'hey';
?>

HTML

  • Include alt attribute for all images
  • Include title attribute for all links
  • Close all your tags properly
  • a elements with target="_blank" should include a rel="noopener"

CSS

  • Try to use classes instead of IDs unless things are absolutely unique
  • One selector per line
  • Care with fallbacks and browsers compatibilities. Using only official syntax and let the build process add prefixes as needed.
.class {
    color: #fefe89;
    font-size: 1.1em;
}

.second-class,
.third-class {
    backgound-color: white;
}

Proposing Changes

Make a new branch and push it to GitHub.

git checkout -b feature_branch_name
git push -u origin feature_branch_name

Updating from Main

git pull origin main

Merge from main

git checkout feature_branch_name
git merge main