32
41
Fork
You've already forked website
52

complete the user documentation with Codeberg fallbacks #153

Merged
Ghost merged 21 commits from :wip-user into main 2023年03月08日 15:26:29 +01:00

Preview at https://forgejo.codeberg.page/@pull_153/docs/v1.19/user/

This completes the structure of the user documentation.

It adds some pages with Forgejo adaptations for all pages in the "Getting Started" section. For other pages not yet adapted to Forgejo, a direct link to the Codeberg page is used instead.

It adds all pages that contain user documentation from the Gitea documentation.

The PR allows edits from maintainers, feel free to push any change you think best for a quicker turnaround, I agree in advance to the changes.

Preview at https://forgejo.codeberg.page/@pull_153/docs/v1.19/user/ --- This completes the structure of the user documentation. It adds some pages with Forgejo adaptations for all pages in the "Getting Started" section. For other pages not yet adapted to Forgejo, a direct link to the Codeberg page is used instead. It adds all pages that contain user documentation from the Gitea documentation. The PR allows edits from maintainers, feel free to push any change you think best for a quicker turnaround, I agree in advance to the changes.
Collaborator
Copy link

Preview ready: https://forgejo.codeberg.page/@pull_153/

Preview ready: https://forgejo.codeberg.page/@pull_153/
Ghost force-pushed wip-user from 8a33cda4ee
All checks were successful
forgejo-ci/pr/woodpecker Pipeline was successful
to f609bbffe9
All checks were successful
forgejo-ci/pr/woodpecker Pipeline was successful
2023年03月07日 10:18:12 +01:00 Compare
Ghost force-pushed wip-user from f609bbffe9
All checks were successful
forgejo-ci/pr/woodpecker Pipeline was successful
to d30a8454e1
All checks were successful
forgejo-ci/pr/woodpecker Pipeline was successful
2023年03月07日 10:26:19 +01:00 Compare
Ghost force-pushed wip-user from ab6f6d2566
All checks were successful
forgejo-ci/pr/woodpecker Pipeline was successful
to 067a757e4e
All checks were successful
forgejo-ci/pr/woodpecker Pipeline was successful
2023年03月07日 10:52:25 +01:00 Compare
Ghost force-pushed wip-user from 067a757e4e
All checks were successful
forgejo-ci/pr/woodpecker Pipeline was successful
to abe07b2b9a
All checks were successful
forgejo-ci/pr/woodpecker Pipeline was successful
2023年03月07日 10:54:09 +01:00 Compare
linked-references.md: adapt to Forgejo
All checks were successful
forgejo-ci/pr/woodpecker Pipeline was successful
c7fb2ee0e5
push-options.md: adapt to Forgejo
All checks were successful
forgejo-ci/pr/woodpecker Pipeline was successful
e0bff8362c
agit-support.md: adapt to Forgejo
All checks were successful
forgejo-ci/pr/woodpecker Pipeline was successful
b223f9a1c4
earl-warren left a comment
Copy link
  • Verified all links from the user TOC
  • Browsed all new pages checking if images display well
  • Did not find obvious mistakes
* Verified all links from the user TOC * Browsed all new pages checking if images display well * Did not find obvious mistakes
Ryuno-Ki left a comment
Copy link

I just went through the content, because the links were already checked.

I just went through the content, because the links were already checked.
@ -0,0 +9,4 @@
## Creating PRs
Agit allows to create PRs while pushing code to the remote repo. \
Contributor
Copy link

What's the meaning of `\

What's the meaning of `\

I don't know.

I don't know.
Contributor
Copy link

Can we ask delvh? Not sure whether the person is on Matrix or Mastodon

https://github.com/go-gitea/gitea/pull/21027#discussion_r961460759

Can we ask delvh? Not sure whether the person is on Matrix or Mastodon https://github.com/go-gitea/gitea/pull/21027#discussion_r961460759
@ -0,0 +214,4 @@
|-----------|--------------------------------------------------------------------------------------------------|----------|---------|---------|--------------------------------------------------------------------------|
| 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) |
Contributor
Copy link

As far as I know there are many different engines for parsing regular expressions.
Assuming we are using Go's variant of it (instead of a JavaScript one), can we link to something more specific?

As far as I know there are many different engines for parsing regular expressions. Assuming we are using Go's variant of it (instead of a JavaScript one), can we link to something more specific?

That would require a little bit of investigation.

That would require a little bit of investigation.
Contributor
Copy link

#168

https://codeberg.org/forgejo/website/issues/168
Ryuno-Ki marked this conversation as resolved
@ -0,0 +28,4 @@
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.
Contributor
Copy link

Is this true for a private repo as well?

Is this true for a private repo as well?

No. Private repo have private issues.

No. Private repo have private issues.
Ghost marked this conversation as resolved
@ -0,0 +40,4 @@
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.
Contributor
Copy link

Those examples might discourage.

Perhaps better to pick a bug vs. enhancement?

Those examples might discourage. Perhaps better to pick a bug vs. enhancement?
Contributor
Copy link

#155

https://codeberg.org/forgejo/website/issues/155
Ryuno-Ki marked this conversation as resolved
@ -0,0 +46,4 @@
or a discussion and, if applicable, the implementation of a solution (or the rejection of
the issue).
Finally, the issue is closed, thus vanishing from the list of open issues.
Contributor
Copy link

I'd rather say that the issue is moved to the closed tab.
Vanishing might hint that the issue is somehow deleted.

I'd rather say that the issue is moved to the closed tab. Vanishing might hint that the issue is somehow deleted.
Contributor
Copy link

ccf81db1ab

https://codeberg.org/forgejo/website/commit/ccf81db1abb3c09cc3f6e629a007870962dc2be0
Ryuno-Ki marked this conversation as resolved
@ -0,0 +61,4 @@
#### 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
Contributor
Copy link

Except „many" is an exaggeration in my experience.

Except „many" is an exaggeration in my experience.
Contributor
Copy link

#156

https://codeberg.org/forgejo/website/issues/156
Ryuno-Ki marked this conversation as resolved
@ -0,0 +65,4 @@
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
Contributor
Copy link

We might also link to the Responsible Disclosure Process here.
There could be projects that just ignore security notifications.

We might also link to the Responsible Disclosure Process here. There could be projects that just ignore security notifications.
Contributor
Copy link

#157

https://codeberg.org/forgejo/website/issues/157
Ryuno-Ki marked this conversation as resolved
@ -0,0 +76,4 @@
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
Contributor
Copy link

This leaves the option open that you are affected by an issue, that was already closed (because stale, for example) and is not resolved.

This leaves the option open that you are affected by an issue, that was already closed (because stale, for example) and is not resolved.
Contributor
Copy link

#158

https://codeberg.org/forgejo/website/issues/158
Ryuno-Ki marked this conversation as resolved
@ -0,0 +80,4 @@
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.
Contributor
Copy link

It might be helpful to list these questions to be answered:

  1. What did you do? (Steps to reproduce)
  2. What did you expect to happen?
  3. What happened instead? (Screenshots, log files etc)
It might be helpful to list these questions to be answered: 1. What did you do? (Steps to reproduce) 1. What did you expect to happen? 3. What happened instead? (Screenshots, log files etc)
Contributor
Copy link

#159

https://codeberg.org/forgejo/website/issues/159
Ryuno-Ki marked this conversation as resolved
@ -0,0 +10,4 @@
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 the main branch.
Contributor
Copy link

main as in the branch with that name?
Or the default branch?
Could it be any branch?

`main` as in the branch with that name? Or the default branch? Could it be any branch?

It is any branch, I removed "to the main branch".

It is any branch, I removed "to the main branch".
Ghost marked this conversation as resolved
@ -0,0 +82,4 @@
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
Contributor
Copy link

Out of curiousity: How is that link resolved?
Is this something Astro does for us?

Out of curiousity: How is that link resolved? Is this something Astro does for us?
Contributor
Copy link

#160

https://codeberg.org/forgejo/website/issues/160
Ryuno-Ki marked this conversation as resolved
@ -0,0 +162,4 @@
| 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` |
Contributor
Copy link

Here you use yes/no instead of the emojis.
Should we stick to one format?

Here you use yes/no instead of the emojis. Should we stick to one format?
Contributor
Copy link

#161

https://codeberg.org/forgejo/website/issues/161
Ryuno-Ki marked this conversation as resolved
@ -0,0 +7,4 @@
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.
Contributor
Copy link

Should we name the default value here as well?

Should we name the default value here as well?
Contributor
Copy link

#166

https://codeberg.org/forgejo/website/issues/166
Ryuno-Ki marked this conversation as resolved
@ -0,0 +16,4 @@
Example of changing a repository's visibility to public:
```shell
git push -o repo.private=false -u origin master
Contributor
Copy link

~~Is ~~

My comment got lost somehow and I don't recall what was on my mind.

~~Is ~~ My comment got lost somehow and I don't recall what was on my mind.
Ryuno-Ki marked this conversation as resolved
@ -0,0 +21,4 @@
<table class="table">
<thead>
<tr>
<th> Task </th>
Contributor
Copy link

Could you add scope attributes here for accessibility?

Could you add [`scope`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/th#attr-scope) attributes here for accessibility?
Contributor
Copy link

9360ec69d3

https://codeberg.org/forgejo/website/commit/9360ec69d3b726e0cfb43a32a861e0f6bb5740d6
Ryuno-Ki marked this conversation as resolved
@ -0,0 +29,4 @@
</thead>
<tbody>
<tr>
<td> View, clone and pull repository </td>
Contributor
Copy link

Since this acts as a kind of matrix, scope="row" sounds useful.
Screenreaders should then read out both scopes for each cell.
(I can check that)

Since this acts as a kind of matrix, `scope="row"` sounds useful. Screenreaders should then read out both scopes for each cell. (I can check that)
Contributor
Copy link

9360ec69d3

https://codeberg.org/forgejo/website/commit/9360ec69d3b726e0cfb43a32a861e0f6bb5740d6
Ryuno-Ki marked this conversation as resolved
@ -0,0 +30,4 @@
<tbody>
<tr>
<td> View, clone and pull repository </td>
<td> <span style="color: green">✅</span> </td>
Contributor
Copy link

Is there a chance that you could use a CSS class and style it this way instead of an inline style?

Is there a chance that you could use a CSS class and style it this way instead of an inline `style`?
Contributor
Copy link

#162

https://codeberg.org/forgejo/website/issues/162
Ryuno-Ki marked this conversation as resolved
@ -0,0 +51,4 @@
</tr>
<tr>
<td> Push directly to repository </td>
<td> <span style="color: red"></span> </td>
Contributor
Copy link

Forgejo isn't showing me any content within the <span> here. On purpose?

Forgejo isn't showing me any content within the `<span>` here. On purpose?

There was something in the Codeberg documentation that was just removed because I did not know what to use as a replacement. But I left the span in case a replacement is found.

There was something in the Codeberg documentation that was just removed because I did not know what to use as a replacement. But I left the span in case a replacement is found.
Contributor
Copy link

I used https://emojipedia.org/cross-mark/ in 48b672b131

I used https://emojipedia.org/cross-mark/ in https://codeberg.org/forgejo/website/commit/48b672b13120b4209ec34b8c9e008051019716bc
Ghost marked this conversation as resolved
@ -0,0 +119,4 @@
- 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, when this is specified, you cannot change units. The team will have admin permissions (See the Admin column under [Collaborators](#collaborators)).
Contributor
Copy link

The first sentence reads a bit bumpy.
Can you explain me what a team with admin access is able (or rather unable) to do?
What's unit referring to here? As in, what do you mean I can't change an issue? (for example)

The first sentence reads a bit bumpy. Can you explain me what a team with admin access is able (or rather unable) to do? What's unit referring to here? As in, what do you mean I can't change an issue? (for example)

This is a poor wording indeed, just replaced with:

When a team is configured to have administrator access, you cannot change units.

Which reflects the reality.

This is a poor wording indeed, just replaced with: > When a team is configured to have administrator access, you cannot change units. Which reflects the reality.
Ghost marked this conversation as resolved
@ -0,0 +121,4 @@
When a team is configured to have administrator access, when this is specified, you cannot change units. The team will have admin permissions (See the Admin column under [Collaborators](#collaborators)).
Currently, there are six units that can be configured:
Contributor
Copy link

Perhaps it makes sense to pull that above the permission levels, because then it's clearer what's meant with unit.

Perhaps it makes sense to pull that above the permission levels, because then it's clearer what's meant with unit.

replaced with anonymous

replaced with anonymous
Ghost marked this conversation as resolved
@ -0,0 +126,4 @@
- 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.
Contributor
Copy link

Does this extend to tags as well?

Does this extend to tags as well?
Ghost marked this conversation as resolved
@ -0,0 +127,4 @@
- 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.
Contributor
Copy link

A wiki might be used for other purposes.

A wiki might be used for other purposes.
Contributor
Copy link

#163

https://codeberg.org/forgejo/website/issues/163
Ryuno-Ki marked this conversation as resolved
@ -0,0 +132,4 @@
There are also two units which can be toggled:
- External Wiki: access to external wiki.
Contributor
Copy link

What's meant with external exactly?

What's meant with external exactly?

A URL to a wiki hosted elsewhere.

A URL to a wiki hosted elsewhere.
Ghost marked this conversation as resolved
@ -0,0 +135,4 @@
- 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.
Contributor
Copy link

You're assuming the team member to be male here.
(From an inclusion perspective this could be debatable).

You're assuming the team member to be male here. (From an inclusion perspective this could be debatable).
Contributor
Copy link

#164

https://codeberg.org/forgejo/website/issues/164
Ryuno-Ki marked this conversation as resolved
@ -0,0 +5,4 @@
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.
Contributor
Copy link

Two times „is" in here.

Two times „is" in here.
Ryuno-Ki marked this conversation as resolved
@ -0,0 +14,4 @@
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 unauthenticated guests can access the wiki.
Contributor
Copy link

„unauthenticated" might be too jargon for a non-technical person.

„unauthenticated" might be too jargon for a non-technical person.

replaced with anonymous

replaced with anonymous
Ghost marked this conversation as resolved
@ -0,0 +77,4 @@
Very basic example for a sidebar:
```markdown
- [[Home]]
Contributor
Copy link

This is special syntax that might need explanation as well.

This is special syntax that might need explanation as well.
Contributor
Copy link

#165

https://codeberg.org/forgejo/website/issues/165
Ryuno-Ki marked this conversation as resolved

@Ryuno-Ki feel free to push all cosmetic / rewording changes you'd like for a quicker turn around.

For the questions related to content, could you create separate issues? This PR is about importing content. Your review spotted a number of problem which is good and they can be addressed as independent issues meant to improve the quality of the imported content.

If this PR attempts to do both (importing content and improve the quality of the imported content) it is going to take a long time and while it is happening the topics included won't be documented at all.

@Ryuno-Ki feel free to push all cosmetic / rewording changes you'd like for a quicker turn around. For the questions related to content, could you create separate issues? This PR is about **importing content**. Your review spotted a number of problem which is good and they can be addressed as independent issues meant to **improve the quality of the imported content**. If this PR attempts to do both (**importing content** and **improve the quality of the imported content**) it is going to take a long time and while it is happening the topics included won't be documented at all.
Clarify language on issue closing
All checks were successful
forgejo-ci/pr/woodpecker Pipeline was successful
ccf81db1ab
 
I feel like vanishing might make people believe that an issue is deleted
once it is closed by the system. That's not the case.
Signed-off-by: André Jaenisch <andre.jaenisch@posteo.de>
Add scope attributes in table
All checks were successful
forgejo-ci/pr/woodpecker Pipeline was successful
9360ec69d3
 
This should provide more semantics to aid assistive technology.
Signed-off-by: André Jaenisch <andre.jaenisch@posteo.de>
Contributor
Copy link

I broke out the question I understand to be polishing into new issues.
Then I edited two files I were confident enough to know what I was doing.

There are still some unsolved comments in this PR from me that I'd like you to answer.

I broke out the question I understand to be polishing into new issues. Then I edited two files I were confident enough to know what I was doing. There are still some unsolved comments in this PR from me that I'd like you to answer.

That makes a fantastic set of issues that are low hanging fruit!

That makes a fantastic set of issues that are low hanging fruit!
address Ryuno-Ki comments
All checks were successful
forgejo-ci/pr/woodpecker Pipeline was successful
d090b8da45

I addressed the comments the best I could. There are two for which I don't have an answer.

I addressed the comments the best I could. There are two for which I don't have an answer.
Inserted crosses for unsupported use cases
All checks were successful
forgejo-ci/pr/woodpecker Pipeline was successful
48b672b131
 
Signed-off-by: André Jaenisch <andre.jaenisch@posteo.de>
Ryuno-Ki left a comment
Copy link

This should work for most cases now.
We have follow-up issues to address the remaining questions.

This should work for most cases now. We have follow-up issues to address the remaining questions.
Contributor
Copy link

I broke one of those two remaining questions into another issue, pushed a commit to handle unsupported use-cases in the table and investigated the source for the last one:

#153 (comment)

Now perhaps wait for the website to build again to manually check for obvious errors. I'm confident that it will work now.

I broke one of those two remaining questions into another issue, pushed a commit to handle unsupported use-cases in the table and investigated the source for the last one: https://codeberg.org/forgejo/website/pulls/153#issuecomment-828126 Now perhaps wait for the website to build again to manually check for obvious errors. I'm confident that it will work now.
Ghost deleted branch wip-user 2023年03月08日 15:26:29 +01:00
Sign in to join this conversation.
Labels
Clear labels
404
Broken links or missing content
Accessibility
Accessibility
Blog post
Documentation
Forgejo Documentation
Internationalisation
i18n and l10n
User research - Accessibility
Requires input about accessibility features, likely involves user testing.
User research - Blocked
Do not pick as-is! We are happy if you can help, but please coordinate with ongoing redesign in this area.
User research - Community
Community features, such as discovering other people's work or otherwise feeling welcome on a Forgejo instance.
User research - Config (instance)
Instance-wide configuration, authentication and other admin-only needs.
User research - Errors
How to deal with errors in the application and write helpful error messages.
User research - Filters
How filter and search is being worked with.
User research - Future backlog
The issue might be inspiring for future design work.
User research - Git workflow
AGit, fork-based and new Git workflow, PR creation etc
User research - Labels
Active research about Labels
User research - Moderation
Moderation Featuers for Admins are undergoing active User Research
User research - Needs input
Use this label to let the User Research team know their input is requested.
User research - Notifications/Dashboard
Research on how users should know what to do next.
User research - Rendering
Text rendering, markup languages etc
User research - Repo creation
Active research about the New Repo dialog.
User research - Repo units
The repo sections, disabling them and the "Add more" button.
User research - Security
User research - Settings (in-app)
How to structure in-app settings in the future?
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
4 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
forgejo/website!153
Reference in a new issue
forgejo/website
No description provided.
Delete branch ":wip-user"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?