First Repository Article #79

This PR adds explanations for the New Repository UI. Thank you to @ivan-paleo for the original PR (#76). I have extended it by:

• documenting the other fields of the UI
• changing PolarBear to knut on the screenshot
• providing a webP version for the screenshot
• changing the wording a little bit here and there
• adding a little introduction and three sections to the article, with the last section (first commit) still to be written, but in a separate PR

Please review (and feel free to merge, if approved).

Note that the explanation of the fields part got a little long, with all of its fields explained.

Should we maybe out-source the explanation of less common fields to its own article?

Thanks for the improvements!

I just noticed a typo in the gitignore section:
"You can choose to add a pre-defined file matching the programming language use use now, or add one manually at a later time."

Note that the explanation of the fields part got a little long, with all of its fields explained.

Should we maybe out-source the explanation of less common fields to its own article?

To me, it seems OK as is. It's not really long either, and it's good to know what each field is about (I didn't think about explaining the obvious ones like name and description, but you are right, it should be there too).

• providing a webP version for the screenshot

@lhinderberger: What did you use to convert PNG to webP? What would be the advantages of webP over PNG? I mean, PNG is really standard, open and lossless.

I just noticed a typo in the gitignore section

Whoops 😄 That's supposed to be "you use" instead of "use use".
Thanks for letting me know :)

EDIT: Fixed it

What did you use to convert PNG to webP?

I used the cwebp command with the -lossless option:

cwebp -lossless foo.png -o foo.webp

What would be the advantages of webP over PNG?

The main advantage of webP is that it usually produces a lot smaller files than both PNG and JPEG (without the artifacts that JPEG produces on geometric forms, too). That means we can reduce traffic by quite a bit (relatively speaking) when using it consistently across the site.

webP is very well supported in modern browsers (except Safari, but it seems they will support it in their next major release). For situations where webP is not supported, we also provide an alternative PNG version (or JPEG, depending on whether its a photo or geometric/screenshot image) using the <picture> tag.

What did you use to convert PNG to webP?

I used the cwebp command with the -lossless option:

cwebp -lossless foo.png -o foo.webp

I guess you use Linux. How would that work on Windows?? As I wrote, when it comes to command lines, Windows is special (and not in a good way apparently ;) )

If I can make it work, I would be able to convert myself and commit with the webP images rather than PNGs.

According to Wikipedia, a wide array of graphics software supports webp too. I suggest to use GIMP - trying it here (on Linux though), (削除) it works without any issues :) (削除ここまで) EDIT: GIMP currently adds a thumbnail to webp, inflating its size. YMMV.

If you do want to use the command line, it appears that there are windows binaries of the cwebp tool available as well.

Indeed, it works with GIMP!

I'll add the section about the first commit now in this PR, so we can merge everything to master in one go.

The extended first repository article is now ready for review and merge :)

I've quickly checked the new parts: to me it seems a bit redundant to the article "Clone & Commit via HTTP", but actually with more details
I would (but this is just my opinion) rather develop the article on "Clone & Commit via HTTP" to include all your edits on that topic.
I would do that for 3 reasons:

• there is no true difference between the first commit and the next ones
• you address only via HTTP from the command line; an introductory article should give an overview of the possibilities rather than the details of one possibility
• it becomes difficult to know where to find the information (to me it makes more sense in the section "working with Git repos").

But again, just my opinion.

This is an introductory guide, not a reference. Its goal is to guide a beginner with no prior experience from registering on Codeberg to making their first commit - as directly and comprehensively as possible.

Thus it is better to limit the scope to one particular, straightforward way of doing things and to explain that one way well than to drown a beginner in a sea of possibilities.

Replacing this essential section with merely a link to the "Clone & Commit via HTTP" article would take readers out of the flow when working their way through the Getting Started guide.

Yes, this approach leads to some redundancy, but it is there to cater to different audiences. That way we can, at the same time, make the Getting Started guide more beginner-friendly and the "Working with Git" section more reference-y, without alienating any audience group. Besides, this process rarely ever changes, so it's not really essential to minimize redundancy.

This is not to say that we cannot also develop the "Clone & Commit" articles, but I would go in a different, more advanced or reference-y direction for these.

Reviewers wanted - maybe @n, @hw or @sexybiggetje? :)

What did you use to convert PNG to webP?
I guess you use Linux. How would that work on Windows?? As I wrote, when it comes to command lines, Windows is special (and not in a good way apparently ;) )

gitforwindows installs a bash client for windows as well, which works fine, but you can install most distro's in WSL which interoperates with your Windows filesystem. (It mounts it). In the past I've seen people use this, but its not recently updated. Looks like it still works; https://github.com/samuelcarreira/webPGUI

Ok so my comments made it across the line when adding the review comment.
This is good solid and clear writing; yay for all who contributed.

Thank you for your comments! :)

I fixed the typos and wording issues, (except for the Gitea one - see my suggestion above).

Good job on that!

Thank you for adding me as co-author too! But I'm wondering why github.com shows up for me (see screenshot)...?

@ivan-paleo That's the same email address as the one in git log, which suggests that your local Git installation is set up to perform commits with your GitHub email address.

To make sure, please check the results of

git config --global user.email

If that also shows the GitHub email address, you need to adjust that setting (at least for Codeberg-related repositories).

@ivan-paleo That's the same email address as the one in git log, which suggests that your local Git installation is set up to perform commits with your GitHub email address.

To make sure, please check the results of

git config --global user.email

If that also shows the GitHub email address, you need to adjust that setting (at least for Codeberg-related repositories).

Indeed... Now I remember that I changed that once and forgot about it. I didn't expect I could commit on Codeberg with my GitHub account...!

I know how to change it globally, but how do I do it only for Codeberg repos?

In any case, I don't really want my email address to be shown here; how can I hide it?

I know how to change it globally, but how do I do it only for Codeberg repos?

Within the relative repo, without the --global flag should work, I think.

I know how to change it globally, but how do I do it only for Codeberg repos?

Within the relative repo, without the --global flag should work, I think.

Oh, so I have to do that for each Codeberg repo??

Seems like it. Either that or you set your Codeberg email as the global default (with the --global flag) and adapt it for your Github repos.

Or you do it like me and have a dedicated email address for Git, which is valid everywhere. There's a lot of options...

In any case, I don't really want my email address to be shown here; how can I hide it?

That question might be worth opening a question in Codeberg/Community. I personally have no idea how to do this here on Codeberg, as I never had the need to do that, personally. But I'm quite sure someone on Codeberg/Community can help you.

If needed you can rewrite history to change accidentally committed email addresses etc, be careful with force-pushing tho, as literally everything can be rewritten.

Generally, the email address in commits is used to assign your avatar to UI items, but does not need to be your primary email.

If needed you can rewrite history to change accidentally committed email addresses etc, be careful with force-pushing tho, as literally everything can be rewritten.

I think I'll refrain from trying! I don't know enough about Git to do it safely. If you guys don't mind that a GitHub user pushed commits to Codeberg, then I'm OK with the history as it is.

Generally, the email address in commits is used to assign your avatar to UI items, but does not need to be your primary email.

Now that I've changed it, my commits are indeed associted with my avatar and link to my Codeberg account, as it should (have) be(en)!

If needed you can rewrite history to change accidentally committed email addresses etc, be careful with force-pushing tho, as literally everything can be rewritten.

I think I'll refrain from trying! I don't know enough about Git to do it safely. If you guys don't mind that a GitHub user pushed commits to Codeberg, then I'm OK with the history as it is.

That is not a problem. We're glad to have you as contributor :)

surely not a problem. If you'd like to change this before merging the PR, you can rewrite history via force push for example like described here.

(to do it after merge, one of the repo owners has to do it via force-push (needs enabled setting in UI), be extra careful here)

full story here: https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History

Thanks @hw for the explanations. It doesn't matter much to me, and I don't want to mess things up!