diff --git a/.github/workflows/main.yaml b/.github/workflows/main.yaml index 562ed53f07..ca390c0918 100644 --- a/.github/workflows/main.yaml +++ b/.github/workflows/main.yaml @@ -74,28 +74,28 @@ jobs: ${{ runner.os }}-composer- - name: Install dependencies - run: nix-shell --run 'npm run install-dependencies' + run: nix-shell --run 'just install-dependencies' - name: Check front-end code if: matrix.check_client - run: nix-shell --run 'npm run check:client' + run: nix-shell --run 'just check-client' - name: Check syntax of back-end code - run: nix-shell --run 'npm run lint:server' + run: nix-shell --run 'just lint-server' - name: Lint back-end code if: matrix.cs_fixer - run: nix-shell --run 'npm run cs:server' + run: nix-shell --run 'just cs-server' - name: Run unit tests - run: nix-shell --run 'npm run test:server' + run: nix-shell --run 'just test-server' - name: Analyse back-end code if: matrix.phpstan - run: nix-shell --run 'npm run analyse:server' + run: nix-shell --run 'just analyse-server' - name: Run integration tests - run: SELFOSS_TEST_STORAGE_BACKEND=${{ matrix.storage }} nix-shell --run 'npm run test:integration' + run: SELFOSS_TEST_STORAGE_BACKEND=${{ matrix.storage }} nix-shell --run 'just test-integration' deploy: name: 'Upload artefacts' @@ -137,7 +137,7 @@ jobs: - name: Build a zipball id: zipball run: | - nix-shell --run 'npm run dist' + nix-shell --run 'just dist' echo "file_name=$(echo selfoss-*.zip)" >> "$GITHUB_OUTPUT" echo "version=$(echo selfoss-*.zip | sed -e 's/^selfoss-//' -e 's/\.zip$//')" >> "$GITHUB_OUTPUT" diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index eeca34c3c9..46d60473cf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,7 +9,7 @@ If you discover a bug or wish to have a feature added, [report it to the issue t We accept [pull requests](https://github.com/fossar/selfoss/compare) with your changes. -Every patch is expected to adhere to our coding style, which is checked automatically by CI. You can install the checkers locally using `npm run install-dependencies`, and then run the checks using `npm run check` before submitting a pull request. There is also `npm run fix`, that will attempt to fix the formatting. +Every patch is expected to adhere to our coding style, which is checked automatically by CI. You can install the checkers locally using just install-dependencies, and then run the checks using `just check` before submitting a pull request. There is also `just fix`, that will attempt to fix the formatting. Please try to make commits small and self-contained. If you need to tweak something you previously committed, squash the new changes into the original commit before the PR is merged. `git commit --fixup` and `git rebase --autosquash` will help you, see https://dev.to/koffeinfrei/the-git-fixup-workflow-386d. diff --git a/NEWS.md b/NEWS.md index ca53ec8738..d0bdd6f88d 100644 --- a/NEWS.md +++ b/NEWS.md @@ -41,6 +41,7 @@ - Source filters are stricter, they need to start and end with a `/`. ([#1423](https://github.com/fossar/selfoss/pull/1423)) - OPML importer has been merged into the React client. ([#1442](https://github.com/fossar/selfoss/pull/1442)) - Web requests will send `Accept-Encoding` header. ([#1482](https://github.com/fossar/selfoss/pull/1482)) +- Developers, we replaced `npm` with [`just`](https://github.com/casey/just) for running build commands and other development tasks. Build the package using `just dist` and check the code using `just check`; see the `justfile` file in the root. ([#1492](https://github.com/fossar/selfoss/pull/1492)) ## 2.19 – 2022-10-12 **This version requires PHP ~~5.6~~ 7.2 (see known regressions section) or newer. It is also the last version to support PHP 7.** diff --git a/README.md b/README.md index 3a2c85771b..57508a227b 100644 --- a/README.md +++ b/README.md @@ -67,15 +67,17 @@ We recommend [Reader For Selfoss](https://f-droid.org/packages/bou.amine.apps.re ## Development -Selfoss uses [composer](https://getcomposer.org/) and [npm](https://www.npmjs.com/get-npm) for installing external libraries. When you clone the repository you have to issue `composer install` to retrieve the external sources. +Selfoss uses [composer](https://getcomposer.org/) and [npm](https://www.npmjs.com/get-npm) for installing external libraries. -For the client side, you will also need JavaScript dependencies installed by calling `npm install` in the `client/` directory. You can use `npm run install-dependencies` as a shortcut for installing both sets of dependencies. +For convenience, we use [`just`](https://github.com/casey/just) command runner (like a modern `make`) to run common development tasks. -We use [Parcel](https://parceljs.org/) (installed by the command above) to build the client side of selfoss. Every time anything in `client/` directory changes, you will need to run `npm run build` for the client to be built and installed into the `public` directory. When developing, you can also use `npm run dev`; it will watch for asset changes, rebuild the bundles as needed, and reload selfoss automatically. Upon switching between `npm run dev` and `npm run build`, you may need to delete `client/.cache`. +When you clone the repository, you have to issue `composer install` to retrieve the external sources. For the client side, you will also need JavaScript dependencies installed by calling `npm install` in the `client/` directory. You can use `just install-dependencies` as a shortcut for installing both sets of dependencies. -If you want to create a package with all the dependencies bundled, you can run `npm run dist` command to produce a zipball. +We use [Parcel](https://parceljs.org/) (installed by the command above) to build the client side of selfoss. Every time anything in `client/` directory changes, you will need to run `just build` for the client to be built and installed into the `public` directory. When developing, you can also use `just dev`; it will watch for asset changes, rebuild the bundles as needed, and reload selfoss automatically. Upon switching between `just dev` and `just build`, you may need to delete `client/.cache`. -Every patch is expected to adhere to our coding style, which is checked automatically by CI. You can install the checkers locally using `npm run install-dependencies`, and then run the checks using `npm run check` before submitting a pull request. There is also `npm run fix`, that will attempt to fix the formatting. +If you want to create a package with all the dependencies bundled, you can run `just dist` command to produce a zipball. + +Every patch is expected to adhere to our coding style, which is checked automatically by CI. You can install the checkers locally using `just install-dependencies`, and then run the checks using `just check` before submitting a pull request. There is also `just fix`, that will attempt to fix the formatting. ## Credits diff --git a/client/justfile b/client/justfile new file mode 100644 index 0000000000..045578c0bd --- /dev/null +++ b/client/justfile @@ -0,0 +1,31 @@ +fix: fix-js fix-styles + +fix-styles: fix-styles-lint fix-styles-prettify + +fix-styles-lint: + npm exec -- stylelint styles/*.scss --fix + +fix-styles-prettify: + npm exec -- prettier styles/*.scss --check --write + +fix-js: + npm exec -- eslint --ext .jsx,.js . --fix + +check: lint-js check-styles + +lint-js: + npm exec -- eslint --ext .jsx,.js . + +check-styles: check-styles-lint check-styles-prettify + +check-styles-lint: + npm exec -- stylelint styles/*.scss + +check-styles-prettify: + npm exec -- prettier styles/*.scss --check + +dev: + npm exec -- parcel watch index.html --dist-dir ../public/ --public-url ./ + +build: + npm exec -- parcel build index.html --dist-dir ../public/ --public-url ./ diff --git a/client/package.json b/client/package.json index 026e866895..3a31ff1022 100644 --- a/client/package.json +++ b/client/package.json @@ -44,19 +44,5 @@ "process": "^0.11.10", "stylelint": "^16.0.0", "stylelint-config-standard-scss": "^13.0.0" - }, - "scripts": { - "fix": "npm run fix:js && npm run fix:styles", - "fix:styles": "npm run fix:styles:lint && npm run fix:styles:prettify", - "fix:styles:lint": "npm run check:styles:lint -- --fix", - "fix:styles:prettify": "npm run check:styles:prettify -- --write", - "fix:js": "npm run lint:js -- --fix", - "check": "npm run lint:js && npm run check:styles", - "lint:js": "eslint --ext .jsx,.js .", - "check:styles": "npm run check:styles:lint && npm run check:styles:prettify", - "check:styles:lint": "stylelint styles/*.scss", - "check:styles:prettify": "prettier styles/*.scss --check", - "dev": "parcel watch index.html --dist-dir ../public/ --public-url ./", - "build": "parcel build index.html --dist-dir ../public/ --public-url ./" } } diff --git a/composer.json b/composer.json index 24d459eaa6..5a9aff1f7d 100644 --- a/composer.json +++ b/composer.json @@ -57,12 +57,5 @@ }, "allow-plugins": false, "sort-packages": true - }, - "scripts": { - "cs": "php-cs-fixer fix --verbose --dry-run --diff", - "fix": "php-cs-fixer fix --verbose --diff", - "lint": "parallel-lint src tests", - "phpstan": "phpstan analyse --memory-limit 512M", - "test": "simple-phpunit --bootstrap tests/bootstrap.php tests" } } diff --git a/docs/content/docs/development/setting-up.md b/docs/content/docs/development/setting-up.md index 36a0d586a1..fe8c7bf961 100644 --- a/docs/content/docs/development/setting-up.md +++ b/docs/content/docs/development/setting-up.md @@ -5,7 +5,7 @@ weight = 10 selfoss makes use of many libraries to make our job as developers easier. To install them, you will need appropriate package managers. The server side uses [composer](https://getcomposer.org/) for PHP libraries and the client side uses [npm](https://www.npmjs.com/get-npm) for the JavaScript world. -Then you will be able to run `npm run install-dependencies` to install the libraries, and `npm run dev` to start a program that will rebuild client-side assets when needed. +Then you will be able to run just install-dependencies to install the libraries, and `just dev` to start a program that will rebuild client-side assets when needed. To run the server side you will need at least [PHP](https://www.php.net/downloads) to be able to run the development server using `php -S 127.0.0.1:8000 run.php`. It would be also nice to have an array of database servers (MySQL and PostgreSQL) and web servers (Apache httpd and nginx) but the server built into PHP and SQLite will suffice for small changes. diff --git a/docs/content/docs/project/release-checklist.md b/docs/content/docs/project/release-checklist.md index 2ff701cad7..16c3d3a0ac 100644 --- a/docs/content/docs/project/release-checklist.md +++ b/docs/content/docs/project/release-checklist.md @@ -4,9 +4,9 @@ weight = 40 +++ 1. Update `NEWS.md` with highlights of changes that are not yet there. Set a release date. -2. Update the version strings throughout the code base to the new release using `npm run bump-version 2.19` and commit the changes. +2. Update the version strings throughout the code base to the new release using `just bump-version 2.19` and commit the changes. 3. Commit the changes. 4. Create a tag using `git tag 2.19`. 5. Push the tag to GitHub `git push origin master --tags`, GitHub actions will automatically build the release tarball and publish the release on GitHub. 6. Netlify will automatically build the website and deploy it. -7. Change the versions to new snapshot `npm run bump-version 2.20-SNAPSHOT`, commit the changes, and push them to the repo to start a new cycle. +7. Change the versions to new snapshot `just bump-version 2.20-SNAPSHOT`, commit the changes, and push them to the repo to start a new cycle. diff --git a/flake.nix b/flake.nix index cd1d9e8f52..9cd37ecab5 100644 --- a/flake.nix +++ b/flake.nix @@ -63,6 +63,9 @@ php php.packages.composer + # Command runner. + pkgs.just + # Back-end code validation. php.packages.phpstan diff --git a/justfile b/justfile new file mode 100644 index 0000000000..78a6338bfa --- /dev/null +++ b/justfile @@ -0,0 +1,49 @@ +analyse-server: + composer exec -- phpstan analyse --memory-limit 512M + +bump-version version: + utils/bump-version.js {{version}} + +check: check-client check-server + +check-client: + just client/check + +check-server: lint-server cs-server test-server analyse-server + +cs-server: + composer exec -- php-cs-fixer fix --verbose --dry-run --diff + +dev: + just client/dev + +build: + just client/build + +dist: + python3 utils/create-zipball.py + +fix: fix-client fix-server + +fix-client: + just client/fix + +fix-server: + composer exec -- php-cs-fixer fix --verbose --diff + +install-dependencies: install-dependencies-client install-dependencies-server + +install-dependencies-client: + npm install --production=false --prefix client/ + +install-dependencies-server: + composer install --dev + +lint-server: + composer exec -- parallel-lint src tests + +test-server: + composer exec -- simple-phpunit --bootstrap tests/bootstrap.php tests + +test-integration: + python3 tests/integration/run.py diff --git a/package.json b/package.json index 8a430f2f13..c9fd589715 100644 --- a/package.json +++ b/package.json @@ -11,25 +11,7 @@ "npm": ">=7" }, "scripts": { - "analyse:server": "composer run-script phpstan", - "bump-version": "$NODE utils/bump-version.js", - "check": "npm run check:client && npm run check:server", - "check:client": "npm run --prefix client/ check", - "check:server": "npm run lint:server && npm run cs:server && npm run test:server && npm run analyse:server", - "cs:server": "composer run-script cs", - "dev": "npm run --prefix client/ dev", - "build": "npm run --prefix client/ build", - "dist": "python3 utils/create-zipball.py", - "fix": "npm run fix:client && npm run fix:server", - "fix:client": "npm run --prefix client/ fix", - "fix:server": "composer run-script fix", - "install-dependencies": "npm run install-dependencies:client && npm run install-dependencies:server", - "install-dependencies:client": "npm install --production=false --prefix client/", - "install-dependencies:server": "composer install --dev", - "lint:server": "composer run-script lint", - "test:server": "composer run-script test", - "test:integration": "python3 tests/integration/run.py", - "postinstall": "npm run install-dependencies" + "postinstall": "just install-dependencies" }, "cacheDirectories": [ "client/node_modules" diff --git a/src/controllers/Index.php b/src/controllers/Index.php index 343bbc9eca..f7dc364835 100644 --- a/src/controllers/Index.php +++ b/src/controllers/Index.php @@ -50,7 +50,7 @@ public function home(): void { $home = BASEDIR . '/public/index.html'; if (!file_exists($home) || ($homeData = file_get_contents($home)) === false) { // For PHPStan: Error will be already handled by global error handler. http_response_code(500); - echo 'Please build the client assets using `npm run build` or obtain a pre-built packages from https://selfoss.aditu.de.'; + echo 'Please build the client assets using `just build` or obtain a pre-built packages from https://selfoss.aditu.de.'; exit; }