What parts of our web interface need further documentation? #67

lhinderberger commented 2020年09月16日 16:58:22 +02:00

In #64, the question was brought up which parts of Codeberg's web interface need further documentation.

@ivan-paleo suggested documenting the Git-related parts of the web interface in greater detail.

It would be great to collect a list of web workflows that need to be documented in this issue.

In #64, the question was brought up which parts of Codeberg's web interface need further documentation. @ivan-paleo suggested documenting the Git-related parts of the web interface in greater detail. It would be great to collect a list of web workflows that need to be documented in this issue.

ivan-paleo commented 2020年09月16日 17:16:35 +02:00

Import of repos: see Documentation #35 and Community #250.

I wouldn't mind writing (some of) the text, but for that I would need to know in which format and what I need to document. Depending on the format, I might not be able to insert it into the documentation myself.

Import of repos: see Documentation [#35](https://codeberg.org/Codeberg/Documentation/issues/35) and Community [#250](https://codeberg.org/Codeberg/Community/issues/250). I wouldn't mind writing (some of) the text, but for that I would need to know in which format and what I need to document. Depending on the format, I might not be able to insert it into the documentation myself.

ivan-paleo commented 2020年09月16日 17:19:50 +02:00

I don't think I can link issues, but #56 is related to it too, right?

I don't think I can link issues, but [#56](https://codeberg.org/Codeberg/Documentation/issues/56) is related to it too, right?

lhinderberger commented 2020年09月16日 17:44:14 +02:00

@ivan-paleo It's always great to see new contributors to Codeberg Documentation - Welcome! :) The articles can be found in the content directory of this repository. They're written in Markdown. To contribute, please fork the repository, commit your contributions to your fork and open a Pull Request.

Can you please explain what you mean with link issues? :) In theory it should be possible to refer to any issue from any other issue - if both issues are in the same repository, it's enough to refer to them by their issue number (EDIT: the link will then be inserted automatically). If they're in different repos, you'll need to prefix the repository's "path", like for example Codeberg/Community#250

@ivan-paleo It's always great to see new contributors to Codeberg Documentation - Welcome! :) The articles can be found in the `content` directory of this repository. They're written in Markdown. To contribute, please fork the repository, commit your contributions to your fork and open a Pull Request. Can you please explain what you mean with link issues? :) In theory it should be possible to refer to any issue from any other issue - if both issues are in the same repository, it's enough to refer to them by their issue number (EDIT: the link will then be inserted automatically). If they're in different repos, you'll need to prefix the repository's "path", like for example Codeberg/Community#250

ivan-paleo commented 2020年09月17日 08:36:40 +02:00

@ivan-paleo It's always great to see new contributors to Codeberg Documentation - Welcome! :) The articles can be found in the content directory of this repository. They're written in Markdown. To contribute, please fork the repository, commit your contributions to your fork and open a Pull Request.

I'll try to do that then; I should be able to write in Markdown :)

Can you please explain what you mean with link issues? :) In theory it should be possible to refer to any issue from any other issue - if both issues are in the same repository, it's enough to refer to them by their issue number (EDIT: the link will then be inserted automatically). If they're in different repos, you'll need to prefix the repository's "path", like for example Codeberg/Community#250

What I meant is not just about adding the link to an issue in a comment, but rather truly link issues like you did (see screenshot).
EDIT: OK, I've just noticed this referencing is automatic, nice!

> @ivan-paleo It's always great to see new contributors to Codeberg Documentation - Welcome! :) The articles can be found in the `content` directory of this repository. They're written in Markdown. To contribute, please fork the repository, commit your contributions to your fork and open a Pull Request. I'll try to do that then; I should be able to write in Markdown :) > Can you please explain what you mean with link issues? :) In theory it should be possible to refer to any issue from any other issue - if both issues are in the same repository, it's enough to refer to them by their issue number (EDIT: the link will then be inserted automatically). If they're in different repos, you'll need to prefix the repository's "path", like for example Codeberg/Community#250 What I meant is not just about adding the link to an issue in a comment, but rather truly link issues like you did (see screenshot). EDIT: OK, I've just noticed this referencing is automatic, nice!

ivan-paleo commented 2020年09月17日 14:31:53 +02:00

@lhinderberger How do I insert screenshots in the documentation:

• where should the file(s) be saved? Is it in assets/images? Should I create a folder there?
• what format?
• what (minimum) size?

Should I commit to (my) master branch, or should I "create a new branch from this commit and start a pull request"?

@lhinderberger How do I insert screenshots in the documentation: * where should the file(s) be saved? Is it in assets/images? Should I create a folder there? * what format? * what (minimum) size? Should I commit to (my) master branch, or should I "create a new branch from this commit and start a pull request"?

ivan-paleo commented 2020年09月17日 15:46:55 +02:00

Regarding the import of repos, I think it should wait a bit, see #250

Regarding the import of repos, I think it should wait a bit, see [#250](https://codeberg.org/Codeberg/Community/issues/250)

lhinderberger commented 2020年09月17日 18:13:08 +02:00

EDIT: OK, I've just noticed this referencing is automatic, nice!

Yes that's right :) Only creating an issue dependency (so, a "hard" dependency of one issue blocking another) requires write permissions to a repository.

> EDIT: OK, I've just noticed this referencing is automatic, nice! Yes that's right :) Only creating an issue dependency (so, a "hard" dependency of one issue blocking another) requires write permissions to a repository.

lhinderberger commented 2020年09月17日 18:24:04 +02:00

@lhinderberger How do I insert screenshots in the documentation:

• where should the file(s) be saved? Is it in assets/images? Should I create a folder there?

Yes, assets/images is the right place for screenshots. Make sure to put them in a directory that matches the path of the article (just like the existing screenshots), to keep a uniform structure. But if they end up in the wrong place, that wouldn't be the end of the world, as it would be fixed when reviewing the PR. :)

• what format?
  Screenshots should be in the PNG format, as its lossless and does not have artifacts on geometric shapes.

Optionally, if you want it to be extra nice, feel free to also add a webp version (please use the -lossless option), embedding it using <picture> tags for smooth fallback on Safari (as seen here for example).
That would be super nice, but it's not required.

• what (minimum) size?

It should be large enough that all relevant text can still be recognized. In practice, I have often used a resolution of about 1300x800px

Should I commit to (my) master branch, or should I "create a new branch from this commit and start a pull request"?

Creating a new branch is good practise for PRs, because it makes it easier to work on multiple articles in parallel (for example because one article cannot be pulled yet and you want to start to write the next one).

If you have any further questions, feel free to ask any time! :)

> @lhinderberger How do I insert screenshots in the documentation: > * where should the file(s) be saved? Is it in assets/images? Should I create a folder there? Yes, `assets/images` is the right place for screenshots. Make sure to put them in a directory that matches the path of the article (just like the existing screenshots), to keep a uniform structure. But if they end up in the wrong place, that wouldn't be the end of the world, as it would be fixed when reviewing the PR. :) > * what format? Screenshots should be in the PNG format, as its lossless and does not have artifacts on geometric shapes. **Optionally**, if you want it to be extra nice, feel free to also add a webp version (please use the `-lossless` option), embedding it using `<picture>` tags for smooth fallback on Safari ([as seen here for example](https://codeberg.org/Codeberg/Documentation/raw/branch/master/content/getting-started/issue-tracking-basics.md)). That would be super nice, but it's not required. > * what (minimum) size? It should be large enough that all relevant text can still be recognized. In practice, I have often used a resolution of about 1300x800px > Should I commit to (my) master branch, or should I "create a new branch from this commit and start a pull request"? Creating a new branch is good practise for PRs, because it makes it easier to work on multiple articles in parallel (for example because one article cannot be pulled yet and you want to start to write the next one). If you have any further questions, feel free to ask any time! :)

ivan-paleo commented 2020年09月17日 18:24:28 +02:00

I have specified the links like this
![](/assets/images/clone-commit-via-http/file.png)
but I don't see the images in the preview. I checked your markdown files and they don't show the preview either. Is that normal?

I have specified the links like this `` but I don't see the images in the preview. I checked your markdown files and they don't show the preview either. Is that normal?

ivan-paleo commented 2020年09月17日 18:28:09 +02:00

• what (minimum) size?

It should be large enough that all relevant text can still be recognized. In practice, I have often used a resolution of about 1300x800px

Some of them are smaller, so I might have to specify the dimensions of the image.

Should I commit to (my) master branch, or should I "create a new branch from this commit and start a pull request"?

Creating a new branch is good practise for PRs, because it makes it easier to work on multiple articles in parallel (for example because one article cannot be pulled yet and you want to start to write the next one).

I had to commit in the meantime so I committed to (my) master branch... Is there a way to create the PR to another branch of the Codeberg repo? Alternatively, I could duplicate my Master branch to another one and PR from that new branch, right?

> > * what (minimum) size? > > It should be large enough that all relevant text can still be recognized. In practice, I have often used a resolution of about 1300x800px Some of them are smaller, so I might have to specify the dimensions of the image. > > > Should I commit to (my) master branch, or should I "create a new branch from this commit and start a pull request"? > > Creating a new branch is good practise for PRs, because it makes it easier to work on multiple articles in parallel (for example because one article cannot be pulled yet and you want to start to write the next one). I had to commit in the meantime so I committed to (my) master branch... Is there a way to create the PR to another branch of the Codeberg repo? Alternatively, I could duplicate my Master branch to another one and PR from that new branch, right?

lhinderberger commented 2020年09月17日 18:28:54 +02:00

Are you editing the documentation using the web interface or do you use a local editor and the npm run serve command?

In the latter case, that sounds like a bug that needs further investigation.

The former case seems to be the same problem as in Codeberg/Community#252 - I think it would be worth the effort to reopen that issue with the goal of modifying Gitea to parse URLs starting with a slash as relative to the repository and not as relative to the web root.

Are you editing the documentation using the web interface or do you use a local editor and the `npm run serve` command? In the latter case, that sounds like a bug that needs further investigation. The former case seems to be the same problem as in Codeberg/Community#252 - I think it would be worth the effort to reopen that issue with the goal of modifying Gitea to parse URLs starting with a slash as relative to the repository and not as relative to the web root.

ivan-paleo commented 2020年09月17日 18:31:27 +02:00

Are you editing the documentation using the web interface or do you use a local editor and the npm run serve command?

I've been using the web interface as I don't have a good editor for md files.

But if I specified the path to the images correctly, then I'm OK with not rendering correctly. Or should I specify the whole path? I tried with ./ and without leading slah as well, but no difference.

> Are you editing the documentation using the web interface or do you use a local editor and the `npm run serve` command? I've been using the web interface as I don't have a good editor for md files. But if I specified the path to the images correctly, then I'm OK with not rendering correctly. Or should I specify the whole path? I tried with `./` and without leading slah as well, but no difference.

lhinderberger commented 2020年09月17日 18:32:49 +02:00

I can warmly recommend Visual Studio Code (or VSCodium) for working on Codeberg Documentation - it's intuitive to use, great for Markdown and as a bonus it's a pleasure to look at. 😉

I can warmly recommend Visual Studio Code (or VSCodium) for working on Codeberg Documentation - it's intuitive to use, great for Markdown and as a bonus it's a pleasure to look at. :wink:

lhinderberger commented 2020年09月17日 18:34:04 +02:00

I had to commit in the meantime so I committed to (my) master branch... Is there a way to create the PR to another branch [...]

This StackOverflow question seems to be the solution, if I understood your question correctly :)

> I had to commit in the meantime so I committed to (my) master branch... Is there a way to create the PR to another branch [...] [This StackOverflow question](https://stackoverflow.com/questions/1628563/move-the-most-recent-commits-to-a-new-branch-with-git) seems to be the solution, if I understood your question correctly :)

ivan-paleo commented 2020年09月17日 18:36:56 +02:00

I can warmly recommend Visual Studio Code (or VSCodium) for working on Codeberg Documentation - it's intuitive to use, great for Markdown and as a bonus it's a pleasure to look at. 😉

If I can connect it easily to Git/Codeberg, then I will try that :)

> I can warmly recommend Visual Studio Code (or VSCodium) for working on Codeberg Documentation - it's intuitive to use, great for Markdown and as a bonus it's a pleasure to look at. :wink: If I can connect it easily to Git/Codeberg, then I will try that :)

lhinderberger commented 2020年09月17日 18:43:36 +02:00

It has integrated Git support which makes it possible to clone your repo and make commits, pushes and pulls directly from within the editor. Alternatively, if you already have your repository cloned, you can simply point VS Code to the repository's directory and it should work out-of-the-box.

It has integrated Git support which makes it possible to clone your repo and make commits, pushes and pulls directly from within the editor. Alternatively, if you already have your repository cloned, you can simply point VS Code to the repository's directory and it should work out-of-the-box.

ivan-paleo commented 2020年09月18日 09:15:44 +02:00

I had to commit in the meantime so I committed to (my) master branch... Is there a way to create the PR to another branch [...]

This StackOverflow question seems to be the solution, if I understood your question correctly :)

It seems a bit too complicated for me (remember I don't use Git directly). I see two easy solutions: (1) I just delete my fork (keep a local copy of course), re-fork again, make the changes again (from my local copy), and commit to a new branch; or (2) I create a new branch from my master, and PR from that new branch.
If (2) is OK, I'll do that.

> > I had to commit in the meantime so I committed to (my) master branch... Is there a way to create the PR to another branch [...] > > [This StackOverflow question](https://stackoverflow.com/questions/1628563/move-the-most-recent-commits-to-a-new-branch-with-git) seems to be the solution, if I understood your question correctly :) It seems a bit too complicated for me (remember I don't use Git directly). I see two easy solutions: (1) I just delete my fork (keep a local copy of course), re-fork again, make the changes again (from my local copy), and commit to a new branch; or (2) I create a new branch from my master, and PR from that new branch. If (2) is OK, I'll do that.

ivan-paleo commented 2020年09月18日 09:34:49 +02:00

It has integrated Git support which makes it possible to clone your repo and make commits, pushes and pulls directly from within the editor. Alternatively, if you already have your repository cloned, you can simply point VS Code to the repository's directory and it should work out-of-the-box.

Very easy to use and works perfectly indeed (it's a shame that it's owned by MS...).

> It has integrated Git support which makes it possible to clone your repo and make commits, pushes and pulls directly from within the editor. Alternatively, if you already have your repository cloned, you can simply point VS Code to the repository's directory and it should work out-of-the-box. Very easy to use and works perfectly indeed (it's a shame that it's owned by MS...).

ivan-paleo commented 2020年09月18日 09:41:12 +02:00

Last question (for now): I have tried to make it look as if the user was JohnDoe, but of course I'm not. So I edited the images, but the easiest would be to have access to the same JohnDoe account that you used for the "Getting Started" guide. Would that be possible?

Last question (for now): I have tried to make it look as if the user was JohnDoe, but of course I'm not. So I edited the images, but the easiest would be to have access to the same JohnDoe account that you used for the "Getting Started" guide. Would that be possible?

lhinderberger commented 2020年09月18日 23:19:37 +02:00

If (2) is OK, I'll do that.

I'd not recommend making PRs from your fork's master branch, because it complicates things a lot if a PR is stalled/blocked or (unlikely) rejected.

It would be best to move related changesets to individual branches and have a PR for each of them (i.e. if you're writing an article on markdown and one on the API at the same time, put the commits on two separate branches, depending on which article they belong to).

You can use Git to do that, but I can understand if that's getting a bit complicated (Git is a mighty but slightly frightening beast 😉).

So, option number 1 might be the way to go.

> If (2) is OK, I'll do that. I'd not recommend making PRs from your fork's master branch, because it complicates things a lot if a PR is stalled/blocked or (unlikely) rejected. It would be best to move related changesets to individual branches and have a PR for each of them (i.e. if you're writing an article on markdown and one on the API at the same time, put the commits on two separate branches, depending on which article they belong to). You can use Git to do that, but I can understand if that's getting a bit complicated (Git is a mighty but slightly frightening beast :wink:). So, option number 1 might be the way to go.

lhinderberger commented 2020年09月18日 23:25:04 +02:00

With JohnDoe you mean Knut the icebear, right? :)

There was the idea earlier to give Documentation contributors access to that account. It didn't move forward, as it was a side-track in a now closed issue, but I think we should pick that up again. I'm not sure yet though how to best share the credentials to the Knut account in a safe way though.

Posting the password for grabs in this repository won't fly for pretty obvious reasons 😉 Maybe @n or @hw have an idea how to solve this?

For the time being, you could take the avatar from the Knut account and use it to create your own testing account on codeberg-test.org (the avatar is public domain / CC0-licensed).

With JohnDoe you mean Knut the icebear, right? :) There was the idea earlier to give Documentation contributors access to that account. It didn't move forward, as it was a side-track in a now closed issue, but I think we should pick that up again. I'm not sure yet though how to best share the credentials to the Knut account in a safe way though. Posting the password for grabs in this repository won't fly for pretty obvious reasons :wink: Maybe @n or @hw have an idea how to solve this? For the time being, you could take the avatar from the Knut account and use it to create your own testing account on codeberg-test.org (the avatar is public domain / CC0-licensed).

lhinderberger commented 2020年09月18日 23:25:44 +02:00

For convenience, that would be the one attached below

For convenience, that would be the one attached below

n commented 2020年09月19日 15:10:36 +02:00

Posting the password for grabs in this repository won't fly for pretty obvious reasons 😉 Maybe @n or @hw have an idea how to solve this?

Would a private repo on the docs organization suffice? If necessary, we could also use GPG for encryption though I don't think it's necessary.

We'd also need official permission because the ToS disallows credential sharing.

> Posting the password for grabs in this repository won't fly for pretty obvious reasons :wink: Maybe @n or @hw have an idea how to solve this? Would a private repo on the [docs organization](https://codeberg.org/docs) suffice? If necessary, we could also use GPG for encryption though I don't think it's necessary. We'd also need official permission because the [ToS disallows credential sharing](https://codeberg.org/docs).

lhinderberger commented 2020年09月20日 00:57:25 +02:00

Yes, I think a private repo there would work well for frequent contributors and maintainers of Documentation.

For occasional or one-time contributors, it might be better to allow TODO Screenshot and have the screenshots created by one of the maintainers during review, also with #52 in mind.

Yes, I think a private repo there would work well for frequent contributors and maintainers of Documentation. For occasional or one-time contributors, it might be better to allow `TODO Screenshot` and have the screenshots created by one of the maintainers during review, also with #52 in mind.

ivan-paleo commented 2020年09月21日 08:44:57 +02:00

With JohnDoe you mean Knut the icebear, right? :)

There was the idea earlier to give Documentation contributors access to that account. It didn't move forward, as it was a side-track in a now closed issue, but I think we should pick that up again. I'm not sure yet though how to best share the credentials to the Knut account in a safe way though.

Posting the password for grabs in this repository won't fly for pretty obvious reasons 😉 Maybe @n or @hw have an idea how to solve this?

For the time being, you could take the avatar from the Knut account and use it to create your own testing account on codeberg-test.org (the avatar is public domain / CC0-licensed).

This all sounds like a good idea. I meant a different repo/user though:
https://docs.codeberg.org/git/clone-commit-via-http/

> With JohnDoe you mean Knut the icebear, right? :) > > There was the idea earlier to give Documentation contributors access to that account. It didn't move forward, as it was a side-track in a now closed issue, but I think we should pick that up again. I'm not sure yet though how to best share the credentials to the Knut account in a safe way though. > > Posting the password for grabs in this repository won't fly for pretty obvious reasons :wink: Maybe @n or @hw have an idea how to solve this? > > For the time being, you could take the avatar from the Knut account and use it to create your own testing account on codeberg-test.org (the avatar is public domain / CC0-licensed). This all sounds like a good idea. I meant a different repo/user though: https://docs.codeberg.org/git/clone-commit-via-http/

ivan-paleo commented 2020年09月21日 08:46:20 +02:00

I'd not recommend making PRs from your fork's master branch, because it complicates things a lot if a PR is stalled/blocked or (unlikely) rejected.

It would be best to move related changesets to individual branches and have a PR for each of them (i.e. if you're writing an article on markdown and one on the API at the same time, put the commits on two separate branches, depending on which article they belong to).

You can use Git to do that, but I can understand if that's getting a bit complicated (Git is a mighty but slightly frightening beast 😉).

So, option number 1 might be the way to go.

OK, I'll give my best to do that correctly!
Is there documentation on how to commit on a separate branch using VScode? Or is it just "create new branch from" and then "commit"? Or maybe I'll just use the web interface in this case...!

> I'd not recommend making PRs from your fork's master branch, because it complicates things a lot if a PR is stalled/blocked or (unlikely) rejected. > > It would be best to move related changesets to individual branches and have a PR for each of them (i.e. if you're writing an article on markdown and one on the API at the same time, put the commits on two separate branches, depending on which article they belong to). > > You can use Git to do that, but I can understand if that's getting a bit complicated (Git is a mighty but slightly frightening beast :wink:). > > So, option number 1 might be the way to go. OK, I'll give my best to do that correctly! Is there documentation on how to commit on a separate branch using VScode? Or is it just "create new branch from" and then "commit"? Or maybe I'll just use the web interface in this case...!

n commented 2020年09月21日 09:11:51 +02:00

JohnDoe was used previously by @buhtz I think. That was before @lhinderberger came up with the idea for Knut.

JohnDoe was used previously by @buhtz I think. That was before @lhinderberger came up with the idea for Knut.

ivan-paleo commented 2020年09月21日 09:14:05 +02:00

JohnDoe was used previously by @buhtz I think. That was before @lhinderberger came up with the idea for Knut.

OK, I will then re-do the screenshots with "knut" :) I had to call it "PolarBear" though, because "knut" is already registered.

> JohnDoe was used previously by @buhtz I think. That was before @lhinderberger came up with the idea for Knut. OK, I will then re-do the screenshots with "knut" :) I had to call it "PolarBear" though, because "knut" is already registered.

n commented 2020年09月21日 09:19:06 +02:00

It looks like you can create a branch like this:

It looks like you can create a branch like this: 

ivan-paleo commented 2020年09月21日 14:31:34 +02:00

@n @lhinderberger I have created the first pull request (#76). Before I do it for the rest of what I've written, can you please let me know if I should do things differently (from branching, to writing style...)?

@n @lhinderberger I have created the first pull request (#76). Before I do it for the rest of what I've written, can you please let me know if I should do things differently (from branching, to writing style...)?

ivan-paleo commented 2020年09月22日 17:29:26 +02:00

@ivan-paleo suggested documenting the Git-related parts of the web interface in greater detail.

I have created a PR #78 on just that. Waiting for feedback :)

> @ivan-paleo suggested documenting the Git-related parts of the web interface in greater detail. I have created a PR #78 on just that. Waiting for feedback :)

Ghost commented 2021年05月28日 11:28:05 +02:00

Do we need this issue anymore?

The PR has been merged and there are enough small to medium sized issue for specific topics.
I think we can close this.

Do we need this issue anymore? The PR has been merged and there are enough small to medium sized issue for specific topics. I think we can close this.