earl-warren/docs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Merge pull request 'complete the user documentation with Codeberg fallbacks' (#153) from dachary/website:wip-user into main

Browse source 
Reviewed-on: https://codeberg.org/forgejo/website/pulls/153
Reviewed-by: Earl Warren <earl-warren@noreply.codeberg.org>
Reviewed-by: André Jaenisch <ryuno-ki@noreply.codeberg.org>
This commit is contained in:
Loïc Dachary 2023-03-08 14:26:27 +00:00
commit d2f7a9bb5f
11 changed files with 901 additions and 10 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

BIN
v1.19/_images/user/issue-tracking-basics/issues-list.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 201 KiB

BIN
v1.19/_images/user/wiki/wiki_pageview.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 31 KiB

37
v1.19/user/agit-support.md Normal file
View file

@ -0,0 +1,37 @@
---
layout: '~/layouts/Markdown.astro'
title: 'Agit Setup'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/699f20234b9f7cdbbeeee3be004470c598fa1147/docs/content/doc/usage/agit-support.en-us.md'
---
Limited support for [agit](https://git-repo.info/en/2020/03/agit-flow-and-git-repo/).
## Creating PRs
Agit allows to create PRs while pushing code to the remote repo. \
This can be done by pushing to the branch followed by a specific refspec (a location identifier known to git). \
The following example illustrates this:
```shell
git push origin HEAD:refs/for/master
```
The command has the following structure:
- `HEAD`: The target branch
- `refs/<for|draft|for-review>/<branch>`: The target PR type
- `for`: Create a normal PR with `<branch>` as the target branch
- `draft`/ `for-review`: Currently ignored silently
- `<branch>/<session>`: The target branch to open the PR
- `-o <topic|title|description>`: Options for the PR
- `title`: The PR title
- `topic`: The branch name the PR should be opened for
- `description`: The PR description
- `force-push`: confirm force update the target branch
Here's another advanced example for creating a new PR targeting `master` with `topic`, `title`, and `description`:
```shell
git push origin HEAD:refs/for/master -o topic="Topic of my PR" -o title="Title of the PR" -o description="# The PR Description\nThis can be **any** markdown content.\n- [x] Ok"
```

39
v1.19/user/email-settings.md Normal file
View file

@ -0,0 +1,39 @@
---
layout: '~/layouts/Markdown.astro'
title: 'Email Settings'
license: 'CC-BY-SA-4.0'
origin_url: 'https://codeberg.org/Codeberg/Documentation/src/commit/ceec82002bbdc62cf27974e84df51369a4bfe0f9/content/getting-started/email-settings.md'
---
By default, Forgejo will send notifications to your registered email addresses.
## Configuring all notifications
To change your notification preferences, go to your [Account Settings](https://codeberg.org/user/settings/account) or manually navigate to the settings page.
You can access it by clicking on the menu button “Profile and Settings...” in the top-right corner of Forgejo. From this dropdown, click on Settings, then click on the Account tab.
In the section “Manage Email Addresses”, you can select one of the following options from the drop-down menu for each email address that you have registered with Forgejo:
| Option | Effect |
|:----------------------------|:---------------------------------------------------------------------------------------------------------------|
| Enable Email Notifications | Enables all notifications (default setting) |
| Only Email on Mention | Forgejo will only send an email to this address if your username is mentioned in an issue or a comment |
| Disable Email Notifications | Forgejo will not send any emails to this address |
When you're finished, press the button “Set Email Preference” to confirm your selection.
> **Note:**
> Disabling email notifications doesn't mean that you'll stop receiving important messages from the Forgejo organisation.
## Issue notifications
As soon as you make a comment on an issue, you automatically subscribe to it. Unless you disabled email notifications for all your email addresses, you will get an email for every change and comment on that issue.
You can check and modify your issue subscription status under the “Notifications” section on the menu on the right side of the issue screen.
## Watching repositories
When you watch a repository (by clicking on the “Watch” button in a repository), you will receive emails for every change (creation of issues, pull requests, comments, etc.) done in this repository.
To stop watching a repository, simply click on “Unwatch” in a repository.

44
v1.19/user/index.md
View file

@ -6,13 +6,37 @@ title: 'Forgejo v1.19 user guide'
These documents are targeted to people who are using Forgejo but are not
involved in running it on their machines.
- [Your First Repository](first-repository)
- [Branch and tag protection](protection)
- [Projects / Kanban boards](project)
- [Labels](labels)
- [Webhooks](webhooks)
- Authentication
- [LDAP, PAM, FreeIPA](authentication)
- [OAuth2, Scoped Tokens, Client Types](oauth2-provider)
- [API Usage](api-usage)
- [API Reference](https://codeberg.org/api/swagger)
- Getting started
- [Your First Repository](first-repository)
- [The Basics of Issue Tracking](issue-tracking-basics)
- [Integrated Wiki](wiki)
- [Email Settings](email-settings)
- Collaborating with Others
- [Projects / Kanban boards](project)
- [Pull requests and Git flow](https://docs.codeberg.org/collaborating/pull-requests-and-git-flow/)
- [Invite Collaborators](https://docs.codeberg.org/collaborating/invite-collaborators/)
- [Create and Manage an Organization](https://docs.codeberg.org/collaborating/create-organization/)
- [Repository Permissions](repo-permissions)
- [Resolve Conflicts](https://docs.codeberg.org/collaborating/resolve-conflicts/)
- [Citable Code](https://docs.codeberg.org/collaborating/citable-code/)
- [Labels](labels)
- [Automatically Linked References](linked-references)
- Working with Git Repositories
- [Clone & Commit via Web](https://docs.codeberg.org/git/clone-commit-via-web/)
- [Tags and Releases](https://docs.codeberg.org/git/using-tags/)
- [Branch and tag protection](protection)
- Advanced Usage
- [Issue and Pull Request Templates](issue-pull-request-templates)
- [Generating an Access Token](https://docs.codeberg.org/advanced/access-token/)
- [Webhooks](webhooks)
- Authentication
- [LDAP, PAM, FreeIPA](authentication)
- [OAuth2, Scoped Tokens, Client Types](oauth2-provider)
- [API Usage](api-usage)
- [API Reference](https://codeberg.org/api/swagger)
- [Migrating Repositories](https://docs.codeberg.org/advanced/migrating-repos/)
- [Push Options](push-options)
- [Agit setup](agit-support)
- See also
- [Codeberg guide on Git](https://docs.codeberg.org/git/)
- [Codeberg guide on Markdown](https://docs.codeberg.org/markdown/)

255
v1.19/user/issue-pull-request-templates.md Normal file
View file

@ -0,0 +1,255 @@
---
layout: '~/layouts/Markdown.astro'
title: 'Issue and Pull Request Templates'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/699f20234b9f7cdbbeeee3be004470c598fa1147/docs/content/doc/usage/issue-pull-request-templates.en-us.md'
---
Some projects have a standard list of questions that users need to answer
when creating an issue or pull request. Forgejo supports adding templates to the
main branch of the repository so that they can autopopulate the form when users are
creating issues and pull requests. This will cut down on the initial back and forth
of getting some clarifying details.
Additionally, the New Issue page URL can be suffixed with `?title=Issue+Title&body=Issue+Text` and the form will be populated with those strings. Those strings will be used instead of the template if there is one.
## File names
Possible file names for issue templates:
- `ISSUE_TEMPLATE.md`
- `ISSUE_TEMPLATE.yaml`
- `ISSUE_TEMPLATE.yml`
- `issue_template.md`
- `issue_template.yaml`
- `issue_template.yml`
- `.gitea/ISSUE_TEMPLATE.md`
- `.gitea/ISSUE_TEMPLATE.yaml`
- `.gitea/ISSUE_TEMPLATE.yml`
- `.gitea/issue_template.md`
- `.gitea/issue_template.yaml`
- `.gitea/issue_template.yml`
- `.github/ISSUE_TEMPLATE.md`
- `.github/ISSUE_TEMPLATE.yaml`
- `.github/ISSUE_TEMPLATE.yml`
- `.github/issue_template.md`
- `.github/issue_template.yaml`
- `.github/issue_template.yml`
Possible file names for PR templates:
- `PULL_REQUEST_TEMPLATE.md`
- `PULL_REQUEST_TEMPLATE.yaml`
- `PULL_REQUEST_TEMPLATE.yml`
- `pull_request_template.md`
- `pull_request_template.yaml`
- `pull_request_template.yml`
- `.gitea/PULL_REQUEST_TEMPLATE.md`
- `.gitea/PULL_REQUEST_TEMPLATE.yaml`
- `.gitea/PULL_REQUEST_TEMPLATE.yml`
- `.gitea/pull_request_template.md`
- `.gitea/pull_request_template.yaml`
- `.gitea/pull_request_template.yml`
- `.github/PULL_REQUEST_TEMPLATE.md`
- `.github/PULL_REQUEST_TEMPLATE.yaml`
- `.github/PULL_REQUEST_TEMPLATE.yml`
- `.github/pull_request_template.md`
- `.github/pull_request_template.yaml`
- `.github/pull_request_template.yml`
## Directory names
Alternatively, users can create multiple issue templates inside a special directory and allow users to choose one that more specifically
addresses their problem.
Possible directory names for issue templates:
- `ISSUE_TEMPLATE`
- `issue_template`
- `.gitea/ISSUE_TEMPLATE`
- `.gitea/issue_template`
- `.github/ISSUE_TEMPLATE`
- `.github/issue_template`
- `.gitlab/ISSUE_TEMPLATE`
- `.gitlab/issue_template`
Inside the directory can be multiple markdown (`.md`) or yaml (`.yaml`/`.yml`) issue templates of the form.
## Syntax for markdown template
```md
---
name: "Template Name"
about: "This template is for testing!"
title: "[TEST] "
ref: "main"
labels:
- bug
- "help needed"
---
This is the template!
```
In the above example, when a user is presented with the list of issues they can submit, this would show as `Template Name` with the description
`This template is for testing!`. When submitting an issue with the above example, the issue title would be pre-populated with
`[TEST] ` while the issue body would be pre-populated with `This is the template!`. The issue would also be assigned two labels,
`bug` and `help needed`, and the issue will have a reference to `main`.
## Syntax for yaml template
This example YAML configuration file defines an issue form using several inputs to report a bug.
```yaml
name: Bug Report
about: File a bug report
title: "[Bug]: "
body:
- type: markdown
attributes:
value: |
Thanks for taking the time to fill out this bug report!
- type: input
id: contact
attributes:
label: Contact Details
description: How can we get in touch with you if we need more info?
placeholder: ex. email@example.com
validations:
required: false
- type: textarea
id: what-happened
attributes:
label: What happened?
description: Also tell us, what did you expect to happen?
placeholder: Tell us what you see!
value: "A bug happened!"
validations:
required: true
- type: dropdown
id: version
attributes:
label: Version
description: What version of our software are you running?
options:
- 1.0.2 (Default)
- 1.0.3 (Edge)
validations:
required: true
- type: dropdown
id: browsers
attributes:
label: What browsers are you seeing the problem on?
multiple: true
options:
- Firefox
- Chrome
- Safari
- Microsoft Edge
- type: textarea
id: logs
attributes:
label: Relevant log output
description: Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks.
render: shell
- type: checkboxes
id: terms
attributes:
label: Code of Conduct
description: By submitting this issue, you agree to follow our [Code of Conduct](https://example.com)
options:
- label: I agree to follow this project's Code of Conduct
required: true
```
### Markdown
You can use a `markdown` element to display Markdown in your form that provides extra context to the user, but is not submitted.
Attributes:
| Key | Description | Required | Type | Default | Valid values |
|-------|--------------------------------------------------------------|----------|--------|---------|--------------|
| value | The text that is rendered. Markdown formatting is supported. | Required | String | - | - |
### Textarea
You can use a `textarea` element to add a multi-line text field to your form. Contributors can also attach files in `textarea` fields.
Attributes:
| Key | Description | Required | Type | Default | Valid values |
|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|--------|--------------|---------------------------|
| label | A brief description of the expected user input, which is also displayed in the form. | Required | String | - | - |
| description | A description of the text area to provide context or guidance, which is displayed in the form. | Optional | String | Empty String | - |
| placeholder | A semi-opaque placeholder that renders in the text area when empty. | Optional | String | Empty String | - |
| value | Text that is pre-filled in the text area. | Optional | String | - | - |
| render | If a value is provided, submitted text will be formatted into a codeblock. When this key is provided, the text area will not expand for file attachments or Markdown editing. | Optional | String | - | Languages known to Forgejo. |
Validations:
| Key | Description | Required | Type | Default | Valid values |
|----------|------------------------------------------------------|----------|---------|---------|--------------|
| required | Prevents form submission until element is completed. | Optional | Boolean | false | - |
### Input
You can use an `input` element to add a single-line text field to your form.
Attributes:
| Key | Description | Required | Type | Default | Valid values |
|-------------|--------------------------------------------------------------------------------------------|----------|--------|--------------|--------------|
| label | A brief description of the expected user input, which is also displayed in the form. | Required | String | - | - |
| description | A description of the field to provide context or guidance, which is displayed in the form. | Optional | String | Empty String | - |
| placeholder | A semi-transparent placeholder that renders in the field when empty. | Optional | String | Empty String | - |
| value | Text that is pre-filled in the field. | Optional | String | - | - |
Validations:
| Key | Description | Required | Type | Default | Valid values |
|-----------|--------------------------------------------------------------------------------------------------|----------|---------|---------|--------------------------------------------------------------------------|
| required | Prevents form submission until element is completed. | Optional | Boolean | false | - |
| is_number | Prevents form submission until element is filled with a number. | Optional | Boolean | false | - |
| regex | Prevents form submission until element is filled with a value that match the regular expression. | Optional | String | - | a [regular expression](https://en.wikipedia.org/wiki/Regular_expression) |
### Dropdown
You can use a `dropdown` element to add a dropdown menu in your form.
Attributes:
| Key | Description | Required | Type | Default | Valid values |
|-------------|-----------------------------------------------------------------------------------------------------|----------|--------------|--------------|--------------|
| label | A brief description of the expected user input, which is displayed in the form. | Required | String | - | - |
| description | A description of the dropdown to provide extra context or guidance, which is displayed in the form. | Optional | String | Empty String | - |
| multiple | Determines if the user can select more than one option. | Optional | Boolean | false | - |
| options | An array of options the user can choose from. Cannot be empty and all choices must be distinct. | Required | String array | - | - |
Validations:
| Key | Description | Required | Type | Default | Valid values |
|----------|------------------------------------------------------|----------|---------|---------|--------------|
| required | Prevents form submission until element is completed. | Optional | Boolean | false | - |
### Checkboxes
You can use the `checkboxes` element to add a set of checkboxes to your form.
Attributes:
| Key | Description | Required | Type | Default | Valid values |
|-------------|-------------------------------------------------------------------------------------------------------|----------|--------|--------------|--------------|
| label | A brief description of the expected user input, which is displayed in the form. | Required | String | - | - |
| description | A description of the set of checkboxes, which is displayed in the form. Supports Markdown formatting. | Optional | String | Empty String | - |
| options | An array of checkboxes that the user can select. For syntax, see below. | Required | Array | - | - |
For each value in the options array, you can set the following keys.
| Key | Description | Required | Type | Default | Options |
|----------|------------------------------------------------------------------------------------------------------------------------------------------|----------|---------|---------|---------|
| label | The identifier for the option, which is displayed in the form. Markdown is supported for bold or italic text formatting, and hyperlinks. | Required | String | - | - |
| required | Prevents form submission until element is completed. | Optional | Boolean | false | - |

101
v1.19/user/issue-tracking-basics.md Normal file
View file

@ -0,0 +1,101 @@
---
layout: '~/layouts/Markdown.astro'
title: 'The Basics of Issue Tracking'
license: 'CC-BY-SA-4.0'
origin_url: 'https://codeberg.org/Codeberg/Documentation/src/commit/ceec82002bbdc62cf27974e84df51369a4bfe0f9/content/getting-started/issue-tracking-basics.md'
---
Issues are an important mean of communication on Forgejo.
Besides their original purpose - reporting bugs to a project's maintainer -
they can be used to suggest enhancements, ask for new features, discuss a project's
direction, ask questions and much more.
### The Issue Tracker
![Issues list](../../../../images/v1.19/user/issue-tracking-basics/issues-list.png)
You can access the issue tracker of a project by clicking its "Issues" tab **(1)**.
There, you'll see a browsable and filterable **(2)** list of all issues.
Many projects use labels to categorize issues. If you want to contribute to a project,
a good label to look for is the "help wanted" label.
You can switch between issues that are still open, and those that are already resolved **(3)**.
Some projects define milestones **(4)**, to which issues can be assigned. They are good for
visualizing the progress of a project's development.
You can create an issue by clicking on the green "New Issue" button **(5)** at the top left
of the issues list.
Issues in the issue tracker are public, and everyone is able to read and answer them.
An issue can have an assignee, meaning someone responsible for resolving or moderating
the issue. Their profile picture, with a link to their profile, can be seen in the issue
list.
### Life of an Issue
Once an issue in the Issue Tracker has been created, it will usually pass through a
process of review, discussion and closure, which can be more or less strictly defined,
based on the project you're contributing to.
The first thing that might happen is that your issue is categorized using labels.
Your issue may be reviewed by the project's maintainer(s) and evaluated whether it, i.e., might be a duplicate or an invalid bug report.
Then, depending on what type of issue it is, there might be additional questions
or a discussion and, if applicable, the implementation of a solution (or the rejection of
the issue).
Finally, the issue is closed and moved from the list of open issues to the closed one.
Issues might have dependencies on other issues or pull requests preventing them from being closed.
Occasionally, issues may become "stale". That's when there hasn't been any progress for
an extended period of time (usually months). You might consider reviving these, if there
is a strong interest in getting them resolved (and, preferably, if you can contribute
something to them).
> If you encounter an abandoned project and there's no way of contacting the maintainer(s),
> consider forking it, if you want to assume responsibility for it (or, rather, your fork).
### Things to consider
#### Security bugs
If the bug you have found has security implications, **do not create
an issue right away!** Instead try contacting the project's maintainers privately.
Many projects have a dedicated e-mail address for reporting security bugs. If the
project in question doesn't, consider writing an email directly to the project's
maintainer or ask for the address in the issue tracker.
> **⚠** What's important is that you **don't publicly expose security bugs before they are
> fixed _and_ the fixes are deployed**, because **otherwise, you might put the users of that
> project at severe risk**.
#### Existing issues
Before creating a new issue, please make sure that there isn't already an existing
issue about, i.e., the bug you want to report or the feature you want to request.
If there already is an existing issue, please consider commenting on that issue instead,
if there is something more that you can contribute to it.
You should also make sure that the issue has not already been solved by having a look
at the closed issues **(3)** as well.
#### Try to be precise and helpful
Project maintainers love precise information about why, i.e., a bug is happening.
Some projects may even have templates that specifically ask for information like
the operating system or database software used.
If you can provide that information, it will be easier for the project maintainer(s)
to quickly resolve your issue. And if you want it resolved even quicker,
consider writing a Pull Request solving the issue (if possible).
#### Be (reasonably) patient
Please remember that many project maintainers work on their free software projects
in their free time. Some maintainers may answer you within minutes, others within days.
Don't be discouraged if there isn't an immediate answer.

189
v1.19/user/linked-references.md Normal file
View file

@ -0,0 +1,189 @@
---
layout: '~/layouts/Markdown.astro'
title: 'Automatically Linked References in Issues, Pull Requests and Commit Messages'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/699f20234b9f7cdbbeeee3be004470c598fa1147/docs/content/doc/usage/linked-references.en-us.md'
---
When an issue, pull request or comment is posted, the text description is parsed
in search for references. These references will be shown as links in the Issue View
and, in some cases, produce certain _actions_.
Likewise, commit messages are parsed when they are listed, and _actions_
can be triggered when they are pushed.
To prevent the creation of unintended references, there are certain rules
for them to be recognized. For example, they should not be included inside code
text. They should also be reasonably cleared from their surrounding text
(for example, using spaces).
## User, Team and Organization Mentions
When a text in the form `@username` is found and `username` matches the name
of an existing user, a _mention_ reference is created. This will be shown
by changing the text into a link to said user's profile, and possibly create
a notification for the mentioned user depending on whether they have
the necessary permission to access the contents.
Example:
> [@John](#), can you give this a look?
This is also valid for teams and organizations:
> [@Documenters](#), we need to plan for this.
> [@CoolCompanyInc](#), this issue concerns us all!
Teams will receive mail notifications when appropriate, but whole organizations won't.
Commit messages do not produce user notifications.
## Commits
Commits can be referenced using their SHA1 hash, or a portion of it of
at least seven characters. They will be shown as a link to the corresponding
commit.
Example:
> This bug was introduced in [e59ff077](#)
## Issues and Pull Requests
A reference to another issue or pull request can be created using the simple
notation `#1234`, where _1234_ is the number of an issue or pull request
in the same repository. These references will be shown as links to the
referenced content.
The effect of creating this type of reference is that a _notice_ will be
created in the referenced document, provided the creator of the reference
has reading permissions on it.
Example:
> This seems related to [#1234](#)
Issues and pull requests in other repositories can be referred to as well
using the form `owner/repository#1234`:
> This seems related to [mike/compiler#1234](#)
Alternatively, the `!1234` notation can be used as well. Even when in Forgejo
a pull request is a form of issue, the `#1234` form will always link to
an issue; if the linked entry happens to be a pull request instead, Forgejo
will redirect as appropriate. With the `!1234` notation, a pull request
link will be created, which will be redirected to an issue if required.
However, this distinction could be important if an external tracker is
used, where links to issues and pull requests are not interchangeable.
## Actionable References in Pull Requests and Commit Messages
Sometimes a commit or pull request may fix or bring back a problem documented
in a particular issue. Forgejo supports closing and reopening the referenced
issues by preceding the reference with a particular _keyword_. Common keywords
include "closes", "fixes", "reopens", etc. This list can be
[customized]({{< ref "/doc/advanced/config-cheat-sheet.en-us.md" >}}) by the
site administrator.
Example:
> This PR _closes_ [#1234](#)
If the actionable reference is accepted, this will create a notice on the
referenced issue announcing that it will be closed when the referencing PR
is merged.
For an actionable reference to be accepted, _at least one_ of the following
conditions must be met:
- The commenter has permissions to close or reopen the issue at the moment
of creating the reference.
- The reference is inside a commit message.
- The reference is posted as part of the pull request description.
In the last case, the issue will be closed or reopened only if the merger
of the pull request has permissions to do so.
Additionally, only pull requests and commit messages can create an action,
and only issues can be closed or reopened this way.
The default _keywords_ are:
- **Closing**: close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved
- **Reopening**: reopen, reopens, reopened
## Time tracking in Pull Requests and Commit Messages
When commit or merging of pull request results in automatic closing of issue
it is possible to also add spent time resolving this issue through commit message.
To specify spent time on resolving issue you need to specify time in format
`@<number><time-unit>` after issue number. In one commit message you can specify
multiple fixed issues and spent time for each of them.
Supported time units (`<time-unit>`):
- `m` - minutes
- `h` - hours
- `d` - days (equals to 8 hours)
- `w` - weeks (equals to 5 days)
- `mo` - months (equals to 4 weeks)
Numbers to specify time (`<number>`) can be also decimal numbers, ex. `@1.5h` would
result in one and half hours. Multiple time units can be combined, ex. `@1h10m` would
mean 1 hour and 10 minutes.
Example of commit message:
> Fixed #123 spent @1h, refs #102, fixes #124 @1.5h
This would result in 1 hour added to issue #123 and 1 and half hours added to issue #124.
## External Trackers
Forgejo supports the use of external issue trackers, and references to issues
hosted externally can be created in pull requests. However, if the external
tracker uses numbers to identify issues, they will be indistinguishable from
the pull requests hosted in Forgejo. To address this, Forgejo allows the use of
the `!` marker to identify pull requests. For example:
> This is issue [#1234](#), and links to the external tracker.
> This is pull request [!1234](#), and links to a pull request in Forgejo.
The `!` and `#` can be used interchangeably for issues and pull request _except_
for this case, where a distinction is required. If the repository uses external
tracker, commit message for squash merge will use `!` as reference by default.
## Issues and Pull Requests References Summary
This table illustrates the different kinds of cross-reference for issues and pull requests.
In the examples, `User1/Repo1` refers to the repository where the reference is used, while
`UserZ/RepoZ` indicates a different repository.
| Reference in User1/Repo1 | Repo1 issues are external | RepoZ issues are external | Should render |
| --------------------------- | :-----------------------: | :-----------------------: | ------------------------------------------------------- |
| `#1234` | no | N/A | A link to issue/pull 1234 in `User1/Repo1` |
| `!1234` | no | N/A | A link to issue/pull 1234 in `User1/Repo1` |
| `#1234` | yes | N/A | A link to _external issue_ 1234 for `User1/Repo1` |
| `!1234` | yes | N/A | A link to _PR_ 1234 for `User1/Repo1` |
| `User1/Repo1#1234` | no | N/A | A link to issue/pull 1234 in `User1/Repo1` |
| `User1/Repo1!1234` | no | N/A | A link to issue/pull 1234 in `User1/Repo1` |
| `User1/Repo1#1234` | yes | N/A | A link to _external issue_ 1234 for `User1/Repo1` |
| `User1/Repo1!1234` | yes | N/A | A link to _PR_ 1234 for `User1/Repo1` |
| `UserZ/RepoZ#1234` | N/A | no | A link to issue/pull 1234 in `UserZ/RepoZ` |
| `UserZ/RepoZ!1234` | N/A | no | A link to issue/pull 1234 in `UserZ/RepoZ` |
| `UserZ/RepoZ#1234` | N/A | yes | A link to _external issue_ 1234 for `UserZ/RepoZ` |
| `UserZ/RepoZ!1234` | N/A | yes | A link to _PR_ 1234 for `UserZ/RepoZ` |
| **Alphanumeric issue IDs:** | - | - | - |
| `AAA-1234` | yes | N/A | A link to _external issue_ `AAA-1234` for `User1/Repo1` |
| `!1234` | yes | N/A | A link to _PR_ 1234 for `User1/Repo1` |
| `User1/Repo1!1234` | yes | N/A | A link to _PR_ 1234 for `User1/Repo1` |
| _Not supported_ | N/A | yes | A link to _external issue_ `AAA-1234` for `UserZ/RepoZ` |
| `UserZ/RepoZ!1234` | N/A | yes | A link to _PR_ 1234 in `UserZ/RepoZ` |
_The last section is for repositories with external issue trackers that use alphanumeric format._
_**N/A**: not applicable._
Note: automatic references between repositories with different types of issues (external vs. internal) are not fully supported
and may render invalid links.

20
v1.19/user/push-options.md Normal file
View file

@ -0,0 +1,20 @@
---
layout: '~/layouts/Markdown.astro'
title: 'Push Options'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/699f20234b9f7cdbbeeee3be004470c598fa1147/docs/content/doc/usage/push-options.en-us.md'
---
There is support for some [push options](https://git-scm.com/docs/git-push#Documentation/git-push.txt--oltoptiongt).
- `repo.private` (true|false) - Change the repository's visibility.
This is particularly useful when combined with push-to-create.
- `repo.template` (true|false) - Change whether the repository is a template.
Example of changing a repository's visibility to public:
```shell
git push -o repo.private=false -u origin master
```

137
v1.19/user/repo-permissions.md Normal file
View file

@ -0,0 +1,137 @@
---
layout: '~/layouts/Markdown.astro'
title: 'Repository Permissions'
license: 'CC-BY-SA-4.0'
origin_url: 'https://codeberg.org/Codeberg/Documentation/src/commit/ceec82002bbdc62cf27974e84df51369a4bfe0f9/content/collaborating/repo-permissions.md'
---
<!-- See also https://github.com/go-gitea/gitea/blob/699f20234b9f7cdbbeeee3be004470c598fa1147/docs/content/doc/usage/permissions.en-us.md -->
When you invite collaborators to join your repository or when you create teams for your organization, you have to decide what each collaborator/team is allowed to do.
You can assign teams different levels of permission for each unit (e.g. issues, PR's, wiki).
## Collaborators
There are four permission levels: Read, Write, Administrator and Owner.
The owner is the person who created the repository.
The table below gives an overview of what collaborators are allowed to do when granted each of these permission levels:
<table class="table">
<thead>
<tr>
<th scope="col"> Task </th>
<th scope="col"> Read </th>
<th scope="col"> Write</th>
<th scope="col"> Admin </th>
<th scope="col"> Owner </th>
</thead>
<tbody>
<tr>
<td scope="row"> View, clone and pull repository </td>
<td> <span style="color: green">✅</span> </td>
<td> <span style="color: green">✅</span> </td>
<td> <span style="color: green">✅</span> </td>
<td> <span style="color: green">✅</span> </td>
</tr>
<tr>
<td scope="row"> Contribute pull requests </td>
<td> <span style="color: green">✅</span> </td>
<td> <span style="color: green">✅</span> </td>
<td> <span style="color: green">✅</span> </td>
<td> <span style="color: green">✅</span> </td>
</tr>
<tr>
<td scope="row"> Push to/update contributed pull requests </td>
<td> <span style="color: green">✅</span> </td>
<td> <span style="color: green">✅</span> </td>
<td> <span style="color: green">✅</span> </td>
<td> <span style="color: green">✅</span> </td>
</tr>
<tr>
<td scope="row"> Push directly to repository </td>
<td> <span style="color: red">❌</span> </td>
<td> <span style="color: green">✅</span> </td>
<td> <span style="color: green">✅</span> </td>
<td> <span style="color: green">✅</span> </td>
</tr>
<tr>
<td scope="row"> Merge pull requests </td>
<td> <span style="color: red">❌</span> </td>
<td> <span style="color: green">✅</span> </td>
<td> <span style="color: green">✅</span> </td>
<td> <span style="color: green">✅</span> </td>
</tr>
<tr>
<td scope="row"> Moderate/delete issues and comments </td>
<td> <span style="color: red">❌</span> </td>
<td> <span style="color: green">✅</span> </td>
<td> <span style="color: green">✅</span> </td>
<td> <span style="color: green">✅</span> </td>
</tr>
<tr>
<td scope="row"> Force-push/rewrite history (if enabled) </td>
<td> <span style="color: red">❌</span> </td>
<td> <span style="color: green">✅</span> </td>
<td> <span style="color: green">✅</span> </td>
<td> <span style="color: green">✅</span> </td>
</tr>
<tr>
<td scope="row"> Add/remove collaborators to repository </td>
<td> <span style="color: red">❌</span> </td>
<td> <span style="color: red">❌</span> </td>
<td> <span style="color: green">✅</span> </td>
<td> <span style="color: green">✅</span> </td>
</tr>
<tr>
<td scope="row"> Configure branch settings (protect/unprotect, enable force-push) </td>
<td> <span style="color: red">❌</span> </td>
<td> <span style="color: red">❌</span> </td>
<td> <span style="color: green">✅</span> </td>
<td> <span style="color: green">✅</span> </td>
</tr>
<tr>
<td scope="row"> Configure repository settings (enable wiki, issues, PRs, releases, update profile) </td>
<td> <span style="color: red">❌</span> </td>
<td> <span style="color: red">❌</span> </td>
<td> <span style="color: green">✅</span> </td>
<td> <span style="color: green">✅</span> </td>
</tr>
<tr>
<td scope="row"> Configure repository settings in the danger zone (transfer ownership, delete wiki data / repository, archive repository) </td>
<td> <span style="color: red">❌</span> </td>
<td> <span style="color: red">❌</span> </td>
<td> <span style="color: red">❌</span> </td>
<td> <span style="color: green">✅</span> </td>
</tr>
</tbody>
</table>
## Teams
The permissions for teams are quite configurable. You can specify which repositories a team has access to; therefore, you can specify for each unit (Code Access, Issues, Releases) a different permission level.
Each unit is configured to have one of these 3 permission levels:
- No Access: Members cannot view or take any other action on this unit.
- Read: Members can view the unit, and do standard actions for that unit (See the Read column under [Collaborators](#collaborators)).
- Write: Members can view the unit, and execute write actions that unit (See the Write column under [Collaborators](#collaborators)).
When a team is configured to have administrator access, you cannot change units.
Currently, there are six units that can be configured:
- Code: access source code, files, commits, and branches.
- Issues: organize bug reports, tasks, and milestones.
- Pull Requests: access pull requests, and code reviews.
- Releases: track the project versions and downloads.
- Wiki: access and write documentation.
- Projects: access and manage issues and pull requests in project boards.
There are also two units which can be toggled:
- External Wiki: access to external wiki.
- External Issues: access to the external issue tracker.
A team can be given the permission to create new repositories. When a member of such team creates a new repository, he/she will get administrator access to the repository.

89
v1.19/user/wiki.md Normal file
View file

@ -0,0 +1,89 @@
---
layout: '~/layouts/Markdown.astro'
title: 'Integrated Wiki'
license: 'CC-BY-SA-4.0'
origin_url: 'https://codeberg.org/Codeberg/Documentation/src/commit/ceec82002bbdc62cf27974e84df51369a4bfe0f9/content/getting-started/wiki.md'
---
A [wiki](https://en.wikipedia.org/wiki/Wiki) is a collaborative space on the web. It is a common practice to use wikis to collect knowledge and share information.
Codeberg allows you to add a wiki to a repo for additional documentation.
The user in these examples is `knut`, the polar bear and its repository is `foobar`.
## Activation and Permissions
To enable the wiki for a repository, visit the `Settings` page and activate `Enable Repository Wiki` in the `Advanced Section`. It will default to the built-in wiki which is described here, but you can add an URI to an external site the "Wiki" tab should link to.
> **Warning**
> Be aware that the wiki, once enabled, is accessible for *everyone* who has `read` access to your repository - on public repositories even anonymous guests can access the wiki.
> The wiki is *not* a suitable place for storing private information or secrets (like passwords).
To edit the wiki `write` permission to the repository is required.
## Wiki structure
The wiki is essentially a separate Git repo in your repository with a predefined name in the form of `<your-repository-name>.wiki.git`.
It consists of [Markdown](https://en.wikipedia.org/wiki/Markdown) files (file extension `.md`) and additional assets like images.
No further stylesheets are needed. The Markdown files are automatically rendered according to the selected Forgejo theme.
## Adding content via web
After you have enabled the wiki you are prompted to create the initial page `Home.md`.
The web UI in your browser is currently limited to adding, updating, and deleting pages; you can't manage assets like images this way.
![Wiki home page with edit buttons](../../../../images/v1.19/user/wiki/wiki_pageview.png)
## Adding content via a local Git client
You can work with the wiki repo as you would with any other Git repo on Forgejo.
```shell
git clone git@codeberg.org:knut/foobar.wiki.git
cd foobar.wiki
nano Home.md # or your editor of choice
git commit -am "create Home page"
```
Editing locally allows you to use your favorite editor (preferably with Markdown syntax check and highlighting) and manage additional assets like images.
### Adding images
You can add images to the root directory or a specific subfolder (like `assets` or `images`) using your local Git client.
A feasible workflow might look like this:
```shell
# create a subfolder for images
mkdir images
cd images
# copy the image into this folder
git add images/image.png
git commit -m "add image"
git push
```
Now, you can reference the image in Markdown, like this:
```markdown
![image alt text](images/image.png "image title")
```
After saving your changes, the image should be visible.
> In contrast to embedding external images, images in Git are only rendered after saving the wiki or Markdown file changes.
## Adding a sidebar and a footer
To enhance the usability of your wiki you can add a custom sidebar and a footer that are shown on every page. The sidebar will be displayed to the right of the main content and the footer below.
To enable the sidebar, just add a file named `_Sidebar.md` to your wiki. For a footer the file must be named `_Footer.md`.
Both file types allow common Markdown syntax to adjust the presentation to your needs.
Very basic example for a sidebar:
```markdown
- [[Home]]
### Content
- [Page 1](Page-1)
> knuts wiki
```
> These files starting with `_` are hidden, so in the web UI you need to manually browse for the files. E.g. for our user *knut* and his *foobar* repo:
> `https://codeberg.org/knut/foobar/wiki/_Sidebar`