First Repository Article #79

Merged
n merged 13 commits from first-repo into master 2 years ago

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).

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).
lhinderberger added the
Status: Ready for Review
Kind: Documentation
labels 2 years ago
Poster

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?

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."

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).

> 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.

> - 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.
Poster

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

> I just noticed a typo in the gitignore section Whoops :smile: That's supposed to be "you use" instead of "use use". Thanks for letting me know :) EDIT: Fixed it
Poster

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](https://developers.google.com/speed/webp/docs/cwebp) 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](https://caniuse.com/webp) 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.

> > What did you use to convert PNG to webP? > > I used the [cwebp command](https://developers.google.com/speed/webp/docs/cwebp) 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.
Poster

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.

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!

Indeed, it works with GIMP!
lhinderberger changed title from Explanation for New Repository UI to WIP: First Repository Article 2 years ago
lhinderberger added
Status: In progress
and removed
Status: Ready for Review
labels 2 years ago
Poster

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

I'll add the section about the first commit now in this PR, so we can merge everything to master in one go.
lhinderberger self-assigned this 2 years ago
lhinderberger changed title from WIP: First Repository Article to First Repository Article 2 years ago
lhinderberger added
Status: Ready for Review
and removed
Status: In progress
labels 2 years ago
Poster

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

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.

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.
Poster

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.

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.
Poster

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

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

> > > 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
sexybiggetje requested changes 2 years ago
sexybiggetje left a comment

I've added some comments to the files in this PR. The UI is a bit unclear if they are submitted if not, so I hope they've come across the line.

I've added some comments to the files in this PR. The UI is a bit unclear if they are submitted if not, so I hope they've come across the line.
---
To create a new repository you need to login into your account on Codeberg.org.
Almost everything you can do on Codeberg starts in a repository. Think of a repository as a home for your project, where all of its sourcecode can be organized using Git and which also contains an optional issue tracker and wiki.

We can make this text more feature and future complete, by changing "and which also contains an optional issue tracker and wiki" to "and which also contains optional features like an issue tracker and wiki." since it also provides extra features like Pages, releases/files, etc.

We can make this text more feature and future complete, by changing "and which also contains an optional issue tracker and wiki" to "and which also contains optional features like an issue tracker and wiki." since it also provides extra features like Pages, releases/files, etc.
lhinderberger marked this conversation as resolved
To create a new repository, you need be logged in to your account on Codeberg.org.
After login you can use one of the two buttons shown in the two following screenshot to create a new repository:

screenshot should be pluralized to screenshots in "the two following screenshot to create a new repository"

screenshot should be pluralized to screenshots in "the two following screenshot to create a new repository"
lhinderberger marked this conversation as resolved
- **Description** A short description that appears next to your repository's name where appropriate
- **Template** Occasionally you may want to generate your repository from an existing template repository. In that case, you can specify that template here. Otherwise, simply leave this field empty.
- **Issue Labels** If you want to initialize your project's issue tracker with a set of labels that you can use to categorize issues, you can choose one here. You don't have to choose this right away though, as you can choose and modify issue labels at a later time too.
- **.gitignore** A [.gitignore](https://git-scm.com/docs/gitignore) file defines which files Git should not keep track of. This is for example useful to prevent project configuraiton files or binaries to be checked into version control. You can choose to add a pre-defined file matching the programming language you use now, or add one manually at a later time.

There is a typo in 'configuration' which is misspelled in "prevent project configuraiton files or binaries"

There is a typo in 'configuration' which is misspelled in "prevent project configuraiton files or binaries"
lhinderberger marked this conversation as resolved
For more information on this, have a look at [The Basics of Issue Tracking](/getting-started/issue-tracking-basics)
- **Pull Requests** is where other users can ask you to include a change into your program
- **Releases** is a space where you can upload finished versions of your program, including binaries
- **Wiki** is a very basic wiki built into Gitea

Should we mention Gitea here, or rather Codeberg or "the software" ?

Should we mention Gitea here, or rather Codeberg or "the software" ?
Poster

Maybe "Gitea, the software that Codeberg is based on"?

Maybe "Gitea, the software that Codeberg is based on"?

Good solution!

Good solution!
lhinderberger marked this conversation as resolved
**Variant - HTTPS**
#### 3. Navigate to the cloned repository
After cloning, the repository should now be in a new subdirectory with the same name as your repository, in this case `foobar`

This sentence should end with a full-stop, or a semicolon, depending on your preference.

This sentence should end with a full-stop, or a semicolon, depending on your preference.
lhinderberger marked this conversation as resolved
> If you want to add all changed files in your source tree, you can run `git add .` but **be careful** as this might add unwanted files as well, so it's a good idea to double-check by running `git status` before committing.
#### 3. Commit your changes
By commiting your changes, you create a new step in the version history of your program. They act like snapshots of your program's state at a given point of time, and you will later be able to jump back and forth between them.

Committing should get the extra 't' that it deserves in the first occurance. The title might be changed to '3. Committing your changes' as well.

Committing should get the extra 't' that it deserves in the first occurance. The title might be changed to '3. Committing your changes' as well.
Poster

I'll fix the typo, but I'll leave the heading as-is, due to consistency with the other numbered/step-by-step headings.

I'll fix the typo, but I'll leave the heading as-is, due to consistency with the other numbered/step-by-step headings.
lhinderberger marked this conversation as resolved

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.

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.
lhinderberger added
Status: Review
and removed
Status: Ready for Review
labels 2 years ago
Poster

Thank you for your comments! :)

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

Thank you for your comments! :) I fixed the typos and wording issues, (except for the Gitea one - see my suggestion above).
lhinderberger requested review from sexybiggetje 2 years ago
sexybiggetje approved these changes 2 years ago
n approved these changes 2 years ago
n merged commit 0788c1aa65 into master 2 years ago

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)...?

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)...?
lhinderberger deleted branch first-repo 2 years ago
Poster

@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).

@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?

> @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?

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

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.

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??

> > 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??
Poster

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...

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...
Poster

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.

> 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.
hw commented 2 years ago
Owner

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. 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. > 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)!
n commented 2 years ago
Collaborator

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 :)

> > 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 :)
hw commented 2 years ago
Owner

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.

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](https://stackoverflow.com/questions/34850831/change-git-email-for-previous-commits#34863275).
hw commented 2 years ago
Owner

(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)

(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)
hw commented 2 years ago
Owner
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!

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

Reviewers

sexybiggetje approved these changes 2 years ago
n approved these changes 2 years ago
The pull request has been merged as 0788c1aa65.
Sign in to join this conversation.
No reviewers
No Milestone
No Assignees
5 Participants
Notifications
Due Date

No due date set.

Dependencies

This pull request currently doesn't have any dependencies.

Loading…
There is no content yet.