Developer Documentation
Build-time Dependencies
The following tools are required for app development:
- make: to run the Makefile targets
- curl: to fetch some build tools from the web
- npm: to install NodeJS dependencies and compile JS assets
- g++: to compile some NodeJS dependencies
- rsync and openssl: for generating release tarballs
- php
dom
andsqlite
extension - composer for installing php dependencies
- nextcloud server for running php tests
- teams/circles app for passing some php tests that depend on it
- gh, the Github console command, for releasing to Github
Developer installation
To install the app manually:
- Install a development setup of nextcloud.
- Install the teams/circles, text and viewer apps by cloning them to the
apps
folder - Clone this repository into the
apps
folder of your Nextcloud - Install build tools and dependencies by running
make setup-dev
- Compile NodeJS assets by running
make build
Afterwards, you can enable the app from the Nextcloud app management menu.
Running tests
With the app available in the Nextcloud app management you should be able to run the unit tests with
make test-php-unit
In order to run the integration tests you either need to configure your
Nextcloud to run with https and be availabe at https://nextcloud.local
,
or you need to change the default
config for behat in
tests/Integration/features/config/behat.yml
to use a different baseUrl
.
Then you can run them with
make test-php-integration
The integration tests rely on test data installed to the server. This is
available in the nextcloud-docker-dev
repo.
Development environment
Development environments often do not use proper hostnames and are not using ssl. In order to make the teams API work in such environments, a few configuration settings need to be adjusted.
You can do so by running the following commands on the nextcloud server:
./occ config:system:set --type bool --value true -- allow_local_remote_servers
./occ config:app:set --value 1 -- circles self_signed_cert
./occ config:app:set --value 1 -- circles allow_non_ssl_links
./occ config:app:set --value 1 -- circles local_is_non_ssl
Important developer links
Faster frontend developing with HMR
You can enable HMR (Hot module replacement) to avoid page reloads when working on the frontend:
- ☑️ Install and enable
hmr_enabler
app - 🏁 Run
npm run serve
- 🌍 Open the normal Nextcloud server URL (not the URL given by above command)
Development Background: Collective ownership
Usually, in Nextcloud every file/folder is owned by a user. Even when shared, the ultimate power over this object remains at the owner user. In collective workflows, this leads to several problems. Instead of individual users, we want the collective pages to be owned and maintained by the collective.
That’s why the Collectives app implements an own storage and uses mountpoints to mount the collective folders to members home directories.
Development Background: Teams integration
Every collective is bound to a team. Currently, the app automatically creates a new secret team with every new collective.
Prepare a release
Dependencies for building a new release:
- Nextcloud OCC at
../../occ
and required PHP dependencies - App certificate+key for signing the app at
~/.nextcloud/certificates
Releasing a new version contains the following steps:
- Update
CHANGELOG.md
- Bump version in
appinfo/info.xml
- Make sure the Github CI passes
- Build release and publish to Github and App Store:
make release-github make release-appstore
Backport changes to stableX
branches
App development happens in the main
branch. From time to time, we have to
branch off due to backwards-incompatible changes in the Nextcloud server code.
In these cases, we create a new branch like stable1
(for 1.X releases) that
holds the Collectives version before we break compability with an old release.
To allow backporting changes from the main
branch to these stableX
releases
later, we established the following workflow:
The last backported commit from main
is tagged as backported
. In order to
backport all subsequent commits and prepare a stableX
branch for a new
release, do the following:
- Backport commits since
backported
(replacestableX
with the branch name):git checkout origin/main -b backport/stableX git rebase --onto stableX backported -i git push origin backport/stableX git tag -d backported git push origin --delete backported git tag backported origin/main git push origin --tags
- Create a merge request from
backport/stableX
tostableX
. Merge after pipeline succeeds. - Remove temporary branches:
git branch -D backport/stableX git push origin --delete backport/stableX