diff --git a/v1.19/_images/user/issue-tracking-basics/issues-list.png b/v1.19/_images/user/issue-tracking-basics/issues-list.png new file mode 100644 index 0000000..f939761 Binary files /dev/null and b/v1.19/_images/user/issue-tracking-basics/issues-list.png differ diff --git a/v1.19/_images/user/wiki/wiki_pageview.png b/v1.19/_images/user/wiki/wiki_pageview.png new file mode 100644 index 0000000..19a76fe Binary files /dev/null and b/v1.19/_images/user/wiki/wiki_pageview.png differ diff --git a/v1.19/user/agit-support.md b/v1.19/user/agit-support.md new file mode 100644 index 0000000..bfc60e4 --- /dev/null +++ b/v1.19/user/agit-support.md @@ -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//`: The target PR type + - `for`: Create a normal PR with `` as the target branch + - `draft`/ `for-review`: Currently ignored silently +- `/`: The target branch to open the PR +- `-o `: 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" +``` diff --git a/v1.19/user/email-settings.md b/v1.19/user/email-settings.md new file mode 100644 index 0000000..baf506a --- /dev/null +++ b/v1.19/user/email-settings.md @@ -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. diff --git a/v1.19/user/index.md b/v1.19/user/index.md index 5e627eb..82f9932 100644 --- a/v1.19/user/index.md +++ b/v1.19/user/index.md @@ -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/) diff --git a/v1.19/user/issue-pull-request-templates.md b/v1.19/user/issue-pull-request-templates.md new file mode 100644 index 0000000..90c461c --- /dev/null +++ b/v1.19/user/issue-pull-request-templates.md @@ -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 | - | diff --git a/v1.19/user/issue-tracking-basics.md b/v1.19/user/issue-tracking-basics.md new file mode 100644 index 0000000..a6ec657 --- /dev/null +++ b/v1.19/user/issue-tracking-basics.md @@ -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. diff --git a/v1.19/user/linked-references.md b/v1.19/user/linked-references.md new file mode 100644 index 0000000..b4809ba --- /dev/null +++ b/v1.19/user/linked-references.md @@ -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 +`@` after issue number. In one commit message you can specify +multiple fixed issues and spent time for each of them. + +Supported time units (``): + +- `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 (``) 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. diff --git a/v1.19/user/push-options.md b/v1.19/user/push-options.md new file mode 100644 index 0000000..46a846f --- /dev/null +++ b/v1.19/user/push-options.md @@ -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 +``` diff --git a/v1.19/user/repo-permissions.md b/v1.19/user/repo-permissions.md new file mode 100644 index 0000000..f53303e --- /dev/null +++ b/v1.19/user/repo-permissions.md @@ -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' +--- + + + +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: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Task Read Write Admin Owner
View, clone and pull repository ✅ ✅ ✅ ✅
Contribute pull requests ✅ ✅ ✅ ✅
Push to/update contributed pull requests ✅ ✅ ✅ ✅
Push directly to repository ❌ ✅ ✅ ✅
Merge pull requests ❌ ✅ ✅ ✅
Moderate/delete issues and comments ❌ ✅ ✅ ✅
Force-push/rewrite history (if enabled) ❌ ✅ ✅ ✅
Add/remove collaborators to repository ❌ ❌ ✅ ✅
Configure branch settings (protect/unprotect, enable force-push) ❌ ❌ ✅ ✅
Configure repository settings (enable wiki, issues, PRs, releases, update profile) ❌ ❌ ✅ ✅
Configure repository settings in the danger zone (transfer ownership, delete wiki data / repository, archive repository) ❌ ❌ ❌ ✅
+ +## 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. diff --git a/v1.19/user/wiki.md b/v1.19/user/wiki.md new file mode 100644 index 0000000..d75e9e4 --- /dev/null +++ b/v1.19/user/wiki.md @@ -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 `.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`