mirror of
https://github.com/penpot/penpot-docs.git
synced 2024-07-06 05:41:47 +00:00
Merge branch 'main' into patch-1
This commit is contained in:
commit
c2d4836cac
21
package.json
21
package.json
|
@ -24,19 +24,20 @@
|
|||
},
|
||||
"homepage": "https://docs.penpot.app",
|
||||
"dependencies": {
|
||||
"@11ty/eleventy": "^1.0.0",
|
||||
"@11ty/eleventy-navigation": "^0.3.2",
|
||||
"@11ty/eleventy-plugin-rss": "^1.1.1",
|
||||
"@11ty/eleventy-plugin-syntaxhighlight": "^4.2.0",
|
||||
"@11ty/eleventy": "^2.0.1",
|
||||
"@11ty/eleventy-navigation": "^0.3.5",
|
||||
"@11ty/eleventy-plugin-rss": "^1.2.0",
|
||||
"@11ty/eleventy-plugin-syntaxhighlight": "^5.0.0",
|
||||
"@tigersway/eleventy-plugin-ancestry": "^1.0.3",
|
||||
"@types/markdown-it": "14.1.0",
|
||||
"elasticlunr": "^0.9.5",
|
||||
"eleventy-plugin-metagen": "^1.6.1",
|
||||
"eleventy-plugin-metagen": "^1.8.3",
|
||||
"eleventy-plugin-nesting-toc": "^1.3.0",
|
||||
"eleventy-plugin-youtube-embed": "^1.8.0",
|
||||
"luxon": "^3.2.1",
|
||||
"markdown-it": "^13.0.1",
|
||||
"markdown-it-anchor": "^8.6.6",
|
||||
"eleventy-plugin-youtube-embed": "^1.10.2",
|
||||
"luxon": "^3.4.4",
|
||||
"markdown-it": "^14.1.0",
|
||||
"markdown-it-anchor": "^9.0.1",
|
||||
"markdown-it-plantuml": "^1.4.1"
|
||||
},
|
||||
"packageManager": "yarn@4.1.1"
|
||||
"packageManager": "yarn@4.2.2"
|
||||
}
|
||||
|
|
|
@ -47,8 +47,16 @@ You also can restict the registrations to a closed list of domains:
|
|||
```bash
|
||||
# comma separated list of domains (backend only)
|
||||
PENPOT_REGISTRATION_DOMAIN_WHITELIST=""
|
||||
|
||||
# OR
|
||||
PENPOT_EMAIL_DOMAIN_WHITELIST=path/to/whitelist.txt
|
||||
```
|
||||
|
||||
**NOTE**: Since version 2.1, email whitelisting should be explicitly
|
||||
enabled with `enable-email-whitelist`. For backward compatibility, we
|
||||
autoenable it when `PENPOT_REGISTRATION_DOMAIN_WHITELIST` is set with
|
||||
not-empty content.
|
||||
|
||||
### Demo users ###
|
||||
|
||||
Penpot comes with facilities for fast creation of demo users without the need of a
|
||||
|
@ -62,9 +70,6 @@ You can enable demo users using the following variable:
|
|||
PENPOT_FLAGS="$PENPOT_FLAGS enable-demo-users"
|
||||
```
|
||||
|
||||
They are disabled by default since 1.13.0
|
||||
|
||||
|
||||
### Authentication Providers
|
||||
|
||||
To configure the authentication with third-party auth providers you will need to
|
||||
|
@ -175,8 +180,11 @@ PENPOT_OIDC_ROLES="role1 role2"
|
|||
# not provided, the roles checking will be disabled.
|
||||
PENPOT_OIDC_ROLES_ATTR=
|
||||
```
|
||||
<br />
|
||||
|
||||
Since version 1.6.0:
|
||||
__Since version 1.6.0__
|
||||
|
||||
Added the ability to specify custom OIDC scopes.
|
||||
|
||||
```bash
|
||||
# This settings allow overwrite the required scopes, use with caution
|
||||
|
@ -184,8 +192,12 @@ Since version 1.6.0:
|
|||
# user info. Optional, defaults to `openid profile`.
|
||||
PENPOT_OIDC_SCOPES="scope1 scope2"
|
||||
```
|
||||
<br />
|
||||
|
||||
Since version 1.12.0
|
||||
__Since version 1.12.0__
|
||||
|
||||
Added the ability to specify the name and email attribute to use from
|
||||
the userinfo object for the profile creation.
|
||||
|
||||
```bash
|
||||
# Attribute to use for lookup the name on the user object. Optional,
|
||||
|
@ -196,6 +208,22 @@ PENPOT_OIDC_NAME_ATTR=
|
|||
# if not perovided, the `email` prop will be used.
|
||||
PENPOT_OIDC_EMAIL_ATTR=
|
||||
```
|
||||
<br />
|
||||
|
||||
__Since version 1.19.0__
|
||||
|
||||
Introduced the ability to lookup the user info from the token instead
|
||||
of making a request to the userinfo endpoint. This reduces the latency
|
||||
of OIDC login operations and increases compatibility with some
|
||||
providers that exposes some claims on tokens but not in userinfo
|
||||
endpoint.
|
||||
|
||||
```bash
|
||||
# Set the default USER INFO source. Can be `token` or `userinfo`. By default
|
||||
# is unset (both will be tried, starting with token).
|
||||
|
||||
PENPOT_OIDC_USER_INFO_SOURCE=
|
||||
```
|
||||
|
||||
|
||||
#### Azure Active Directory using OpenID Connect
|
||||
|
@ -424,26 +452,36 @@ headless web browser).
|
|||
## Other flags
|
||||
|
||||
- `enable-cors`: Enables the default cors cofiguration that allows all domains (this
|
||||
configuration is designed only for dev purposes right now).
|
||||
- `enable-backend-api-docs`: Enables the `/api/_doc` endpoint that lists all rpc methods
|
||||
available on backend.
|
||||
configuration is designed only for dev purposes right now)
|
||||
- `enable-backend-api-doc`: Enables the `/api/doc` endpoint that lists all rpc methods
|
||||
available on backend
|
||||
- `enable-insecure-register`: Enables the insecure process of profile registration
|
||||
deactivating the email verification process (only for local or internal setups).
|
||||
- `enable-user-feedback`: Enables the feedback form at the dashboard.
|
||||
deactivating the email verification process (only for local or internal setups)
|
||||
- `disable-secure-session-cookies`: By default, penpot uses the `secure` flag on cookies,
|
||||
this flag disables it; it is usefull if you have plan to serve penpot under different
|
||||
domain than `localhost` without HTTPS.
|
||||
- `disable-login`: allows disable password based login form.
|
||||
domain than `localhost` without HTTPS
|
||||
- `disable-login-with-password`: allows disable password based login form
|
||||
- `disable-registration`: disables registration (still enabled for invitations only).
|
||||
- `enable-prepl-server`: enables PREPL server, used by manage.py and other additional
|
||||
tools for communicate internally with penpot backend.
|
||||
tools for communicate internally with penpot backend
|
||||
|
||||
Since version 1.13.0:
|
||||
__Since version 1.13.0__
|
||||
|
||||
- `enable-log-invitation-tokens`: for cases where you don't have email configured, this
|
||||
will log to console the invitation tokens.
|
||||
will log to console the invitation tokens
|
||||
- `enable-log-emails`: if you want to log in console send emails. This only works if smtp
|
||||
is not configured.
|
||||
is not configured
|
||||
|
||||
__Since version 2.0.0__
|
||||
|
||||
- `disable-onboarding-team`: for disable onboarding team creation modal
|
||||
- `disable-onboarding-newsletter`: for disable onboarding newsletter modal
|
||||
- `disable-onboarding-questions`: for disable onboarding survey
|
||||
- `disable-onboarding`: for disable onboarding modal
|
||||
- `disable-dashboard-templates-section`: for hide the templates section from dashboard
|
||||
- `enable-webhooks`: for enable webhooks
|
||||
- `enable-access-tokens`: for enable access tokens
|
||||
- `disable-google-fonts-provider`: disables the google fonts provider (frontend)
|
||||
|
||||
[1]: /technical-guide/getting-started#configure-penpot-with-elestio
|
||||
[2]: /technical-guide/getting-started#configure-penpot-with-docker
|
||||
|
|
|
@ -94,29 +94,6 @@ using postgresql:
|
|||
pg_dump -h postgres -s > schema.sql
|
||||
```
|
||||
|
||||
|
||||
## Tests ##
|
||||
|
||||
You can run the tests directly with:
|
||||
|
||||
```bash
|
||||
~/penpot/backend$ clojure -M:dev:tests
|
||||
```
|
||||
|
||||
Alternatively, you can run them from a shell. First start a REPL.
|
||||
|
||||
```bash
|
||||
~/penpot/backend$ scripts/repl
|
||||
```
|
||||
|
||||
And then:
|
||||
|
||||
```bash
|
||||
user=> (run-tests)
|
||||
user=> (run-tests 'namespace)
|
||||
user=> (run-tests 'namespace/test)
|
||||
```
|
||||
|
||||
## Linter ##
|
||||
|
||||
There are no watch process for the linter; you will need to execute it
|
||||
|
|
|
@ -228,3 +228,267 @@ This macro enables you to have assertions on production code, that
|
|||
generate runtime exceptions when failed (make sure you handle them
|
||||
appropriately).
|
||||
|
||||
## Unit tests
|
||||
|
||||
We expect all Penpot code (either in frontend, backend or common subsystems) to
|
||||
have unit tests, i.e. the ones that test a single unit of code, in isolation
|
||||
from other blocks. Currently we are quite far from that objective, but we are
|
||||
working to improve this.
|
||||
|
||||
### Running tests with kaocha
|
||||
|
||||
Unit tests are executed inside the [development environment](/technical-guide/developer/devenv).
|
||||
|
||||
We can use [kaocha test runner](https://cljdoc.org/d/lambdaisland/kaocha/), and
|
||||
we have prepared, for convenience, some aliases in `deps.edn` files. To run
|
||||
them, just go to `backend`, `frontend` or `common` and execute:
|
||||
|
||||
```bash
|
||||
# To run all tests once
|
||||
clojure -M:dev:test
|
||||
|
||||
# To run all tests and keep watching for changes
|
||||
clojure -M:dev:test --watch
|
||||
|
||||
# To run a single tests module
|
||||
clojure -M:dev:test --focus common-tests.logic.comp-sync-test
|
||||
|
||||
# To run a single test
|
||||
clojure -M:dev:test --focus common-tests.logic.comp-sync-test/test-sync-when-changing-attribute
|
||||
```
|
||||
|
||||
Watch mode runs all tests when some file changes, except if some tests failed
|
||||
previously. In this case it only runs the failed tests. When they pass, then
|
||||
runs all of them again.
|
||||
|
||||
You can also mark tests in the code by adding metadata:
|
||||
|
||||
```clojure
|
||||
;; To skip a test, for example when is not working or too slow
|
||||
(deftest ^:kaocha/skip bad-test
|
||||
(is (= 2 1)))
|
||||
|
||||
;; To skip it but warn you during test run, so you don't forget it
|
||||
(deftest ^:kaocha/pending bad-test
|
||||
(is (= 2 1)))
|
||||
```
|
||||
|
||||
Please refer to the [kaocha manual](https://cljdoc.org/d/lambdaisland/kaocha/1.91.1392/doc/6-focusing-and-skipping)
|
||||
for how to define custom metadata and other ways of selecting tests.
|
||||
|
||||
**NOTE**: in `frontend` we still can't use kaocha to run the tests. We are on
|
||||
it, but for now we use shadow-cljs with `package.json` scripts:
|
||||
|
||||
```bash
|
||||
yarn run test
|
||||
yarn run test:watch
|
||||
```
|
||||
|
||||
#### Test output
|
||||
|
||||
The default kaocha reporter outputs a summary for the test run. There is a pair
|
||||
of brackets `[ ]` for each suite, a pair of parentheses `( )` for each test,
|
||||
and a dot `.` for each assertion `t/is` inside tests.
|
||||
|
||||
```bash
|
||||
penpot@c261c95d4623:~/penpot/common$ clojure -M:dev:test
|
||||
[(...)(............................................................
|
||||
.............................)(....................................
|
||||
..)(..........)(.................................)(.)(.............
|
||||
.......................................................)(..........
|
||||
.....)(......)(.)(......)(.........................................
|
||||
..............................................)(............)]
|
||||
190 tests, 3434 assertions, 0 failures.
|
||||
```
|
||||
|
||||
All standard output from the tests is captured and hidden, except if some test
|
||||
fails. In this case, the output for the failing test is shown in a box:
|
||||
|
||||
```bash
|
||||
FAIL in sample-test/stdout-fail-test (sample_test.clj:10)
|
||||
Expected:
|
||||
:same
|
||||
Actual:
|
||||
-:same +:not-same
|
||||
╭───── Test output ───────────────────────────────────────────────────────
|
||||
│ Can you see this?
|
||||
╰─────────────────────────────────────────────────────────────────────────
|
||||
2 tests, 2 assertions, 1 failures.
|
||||
```
|
||||
|
||||
You can bypass the capture with the command line:
|
||||
|
||||
```bash
|
||||
clojure -M:dev:test --no-capture-output
|
||||
```
|
||||
|
||||
Or for some specific output:
|
||||
|
||||
```clojure
|
||||
(ns sample-test
|
||||
(:require [clojure.test :refer :all]
|
||||
[kaocha.plugin.capture-output :as capture]))
|
||||
|
||||
(deftest stdout-pass-test
|
||||
(capture/bypass
|
||||
(println "This message should be displayed"))
|
||||
(is (= :same :same)))
|
||||
```
|
||||
|
||||
### Running tests in the REPL
|
||||
|
||||
An alternative way of running tests is to do it from inside the
|
||||
[REPL](/technical-guide/developer/backend/#repl) you can use in the backend and
|
||||
common apps in the development environment.
|
||||
|
||||
We have a helper function `(run-tests)` that refreshes the environment (to avoid
|
||||
having [stale tests](https://practical.li/clojure/testing/unit-testing/#command-line-test-runners))
|
||||
and runs all tests or a selection. It is defined in `backend/dev/user.clj` and
|
||||
`common/dev/user.clj`, so it's available without importing anything.
|
||||
|
||||
First start a REPL:
|
||||
|
||||
```bash
|
||||
~/penpot/backend$ scripts/repl
|
||||
```
|
||||
|
||||
And then:
|
||||
|
||||
```clojure
|
||||
;; To run all tests
|
||||
(run-tests)
|
||||
|
||||
;; To run all tests in one namespace
|
||||
(run-tests 'some.namespace)
|
||||
|
||||
;; To run a single test
|
||||
(run-tests 'some.namespace/some-test)
|
||||
|
||||
;; To run all tests in one or several namespaces,
|
||||
;; selected by a regular expression
|
||||
(run-tests #"^backend-tests.rpc.*")
|
||||
```
|
||||
|
||||
### Writing unit tests
|
||||
|
||||
We write tests using the standard [Clojure test
|
||||
API](https://clojure.github.io/clojure/clojure.test-api.html). You can find a
|
||||
[guide to writing unit tests](https://practical.li/clojure/testing/unit-testing) at Practicalli
|
||||
Clojure, that we follow as much as possible.
|
||||
|
||||
#### Sample files helpers
|
||||
|
||||
An important issue when writing tests in Penpot is to have files with the
|
||||
specific configurations we need to test. For this, we have defined a namespace
|
||||
of helpers to easily create files and its elements with sample data.
|
||||
|
||||
To make handling of uuids more convenient, those functions have a uuid
|
||||
registry. Whenever you create an object, you may give a `:label`, and the id of
|
||||
the object will be stored in the registry associated with this label, so you
|
||||
can easily recover it later.
|
||||
|
||||
You have functions to create files, pages and shapes, to connect them and
|
||||
specify their attributes, having all of them default values if not set.
|
||||
|
||||
Files also store in metadata the **current page**, so you can control in what
|
||||
page the `add-` and `get-` functions will operate.
|
||||
|
||||
```clojure
|
||||
(ns common-tests.sample-helpers-test
|
||||
(:require
|
||||
[app.common.test-helpers.files :as thf]
|
||||
[app.common.test-helpers.ids-map :as thi]
|
||||
[app.common.test-helpers.shapes :as ths]
|
||||
[clojure.test :as t]))
|
||||
|
||||
(t/deftest test-create-file
|
||||
(let [;; Create a file with one page
|
||||
f1 (thf/sample-file :file1)
|
||||
|
||||
;; Same but define the label of the page, to retrieve it later
|
||||
f2 (thf/sample-file :file2 :page-label :page1)
|
||||
|
||||
;; Set the :name attribute of the created file
|
||||
f3 (thf/sample-file :file3 :name "testing file")
|
||||
|
||||
;; Create an isolated page
|
||||
p2 (thf/sample-page :page2 :name "testing page")
|
||||
|
||||
;; Create a second page and add to the file
|
||||
f4 (-> (thf/sample-file :file4 :page-label :page3)
|
||||
(thf/add-sample-page :page4 :name "other testing page"))
|
||||
|
||||
;; Create an isolated shape
|
||||
p2 (thf/sample-shape :shape1 :type :rect :name "testing shape")
|
||||
|
||||
;; Add a couple of shapes to a previous file, in different pages
|
||||
f5 (-> f4
|
||||
(ths/add-sample-shape :shape2)
|
||||
(thf/switch-to-page :page4)
|
||||
(ths/add-sample-shape :shape3 :name "other testing shape"
|
||||
:width 100))
|
||||
|
||||
;; Retrieve created shapes
|
||||
s1 (ths/get-shape f4 :shape1)
|
||||
s2 (ths/get-shape f5 :shape2 :page-label :page3)
|
||||
s3 (ths/get-shape f5 :shape3)]
|
||||
|
||||
;; Check some values
|
||||
(t/is (= (:name f1) "Test file"))
|
||||
(t/is (= (:name f3) "testing file"))
|
||||
(t/is (= (:id f2) (thi/id :file2)))
|
||||
(t/is (= (:id (thf/current-page f2)) (thi/id :page1)))
|
||||
(t/is (= (:id s1) (thi/id :shape1)))
|
||||
(t/is (= (:name s1) "Rectangle"))
|
||||
(t/is (= (:name s3) "testing shape"))
|
||||
(t/is (= (:width s3) 100))
|
||||
(t/is (= (:width (:selrect s3)) 100))))
|
||||
```
|
||||
|
||||
Also there are functions to make some transformations, like creating a
|
||||
component, instantiating it or swapping a copy.
|
||||
|
||||
```clojure
|
||||
(ns app.common-tests.sample-components-test
|
||||
(:require
|
||||
[app.common.test-helpers.components :as thc]
|
||||
[app.common.test-helpers.files :as thf]
|
||||
[app.common.test-helpers.shapes :as ths]))
|
||||
|
||||
(t/deftest test-create-component
|
||||
(let [;; Create a file with one component
|
||||
f1 (-> (thf/sample-file :file1)
|
||||
(ths/add-sample-shape :frame1 :type :frame)
|
||||
(ths/add-sample-shape :rect1 :type :rect
|
||||
:parent-label :frame1)
|
||||
(thc/make-component :component1 :frame1))]))
|
||||
```
|
||||
|
||||
Finally, there are composition helpers, to build typical structures with a
|
||||
single line of code. And the files module has some functions to display the
|
||||
contents of a file, in a way similar to `debug/dump-tree` but showing labels
|
||||
instead of ids:
|
||||
|
||||
```clojure
|
||||
(ns app.common-tests.sample-compositions-test
|
||||
(:require
|
||||
[app.common.test-helpers.compositions :as tho]
|
||||
[app.common.test-helpers.files :as thf]))
|
||||
|
||||
(t/deftest test-create-composition
|
||||
(let [f1 (-> (thf/sample-file :file1)
|
||||
(tho/add-simple-component-with-copy :component1
|
||||
:main-root
|
||||
:main-child
|
||||
:copy-root))]
|
||||
(ctf/dump-file f1 :show-refs? true)))
|
||||
|
||||
;; {:main-root} [:name Frame1] # [Component :component1]
|
||||
;; :main-child [:name Rect1]
|
||||
;;
|
||||
;; :copy-root [:name Frame1] #--> [Component :component1] :main-root
|
||||
;; <no-label> [:name Rect1] ---> :main-child
|
||||
```
|
||||
|
||||
You can see more examples of usage by looking at the existing unit tests.
|
||||
|
||||
|
|
|
@ -296,20 +296,6 @@ msgstr[1] "%s projects"
|
|||
;; => "1 project"
|
||||
```
|
||||
|
||||
## Unit Tests
|
||||
|
||||
Unit tests have to be compiled first, and then run with node.
|
||||
|
||||
```bash
|
||||
npx shadow-cljs compile tests && node target/tests.js
|
||||
```
|
||||
|
||||
Or run the watch (that automatically runs the test):
|
||||
|
||||
```bash
|
||||
npx shadow-cljs watch tests
|
||||
```
|
||||
|
||||
## Integration tests
|
||||
|
||||
### Setup
|
||||
|
@ -330,7 +316,7 @@ Ensure your development environment docker image is up to date.
|
|||
./manage.sh start-devenv
|
||||
```
|
||||
|
||||
**NOTE** You can learn more about how to set up, start and stop our development environment [here](http://localhost:8080/technical-guide/developer/devenv/#getting-started)
|
||||
**NOTE** You can learn more about how to set up, start and stop our development environment [here](/technical-guide/developer/devenv)
|
||||
|
||||
### Running the integration tests
|
||||
|
||||
|
@ -372,7 +358,7 @@ npx playwright test --ui
|
|||
|
||||
> ⚠️ **WARNING:** It is important to be in the right folder (`frontend`) to launch the command above, or you may have errors trying to run the tests.
|
||||
|
||||
> ❗️ **IMPORTANT**: You might need to [install Playwright's browsers and dependencies](https://playwright.dev/docs/intro) in your host machine with: `npx playwright install --with-deps`.
|
||||
> ❗️ **IMPORTANT**: You might need to [install Playwright's browsers and dependencies](https://playwright.dev/docs/intro) in your host machine with: `npx playwright install --with-deps`. In case you are using a Linux distribution other than Ubuntu, [you might need to install the dependencies manually](https://github.com/microsoft/playwright/issues/11122).
|
||||
|
||||
### How to write a test
|
||||
|
||||
|
|
|
@ -4,9 +4,9 @@ title: 15· Teams
|
|||
|
||||
<h1 id="teams">Teams</h1>
|
||||
<p class="main-paragraph">A team is a group of members who collaborate on a collection of projects.
|
||||
Team members are allowed to work with any project or file within the team. The actions that each teamm
|
||||
member is allow to do depend on on their permissions.</p>
|
||||
<p class="main-paragraph">At Penpot you can create and join as many teams as you need and add all necessary stakeholders with no limits about team size.</p>
|
||||
Team members are allowed to work with any project or file within the team. The actions that each team
|
||||
member is allowed to do depends on their permissions.</p>
|
||||
<p class="main-paragraph">At Penpot you can create and join as many teams as you need and add all necessary stakeholders with no team size limits.</p>
|
||||
|
||||
<h2 id="teams-management">Manage teams</h2>
|
||||
<p>At Penpot you can create as many teams as you need and be invited to teams owned by others. Learn how to manage them.</p>
|
||||
|
@ -14,11 +14,11 @@ member is allow to do depend on on their permissions.</p>
|
|||
<h3>Select team</h3>
|
||||
<p>At the top left of the dashboard you can find the team selector.</p>
|
||||
|
||||
<p>"Your Penpot" is the name of your personal space at Penpot. It is like any other team but in which no members can be invited so that you will allways have your own private dashboard. Create or join other teams to collaborate with other Penpot users.</p>
|
||||
<p>"Your Penpot" is the name of your personal space at Penpot. It is like any other team but in which no members can be invited so that you will always have your own private dashboard. Create or join other teams to collaborate with other Penpot users.</p>
|
||||
<figure><img src="/img/teams/team-selector.webp" alt="Teams selector" /></figure>
|
||||
|
||||
<h3>Create teams</h3>
|
||||
<p>To create a new team go to the bottom of the team selector and press "+ Create new team". Then you will be asked to enter a team name and that's it. Once a new team is created you are be able to invite new team members.</p>
|
||||
<p>To create a new team go to the bottom of the team selector and press "+ Create new team". Then you will be asked to enter a team name and that's it. Once a new team is created you are able to invite new team members.</p>
|
||||
<figure><img src="/img/teams/team-selector-projects.webp" alt="Teams selector" /></figure>
|
||||
|
||||
<h3>Delete and leave teams</h3>
|
||||
|
|
Loading…
Reference in New Issue
Block a user