Extend "First Repository" article #56

lhinderberger commented 2020年09月02日 16:36:06 +02:00

While Knut-ifying the images (see #55), I noticed that the "First Repository" article could use some more details.

I'm thinking of guiding a user who had no prior exposure to Git to creating a repository and pushing it to Codeberg. Right now the guide ends at creating an origin remote. It would be nice to add a first commit+push in a step-by-step way.

Also the intricacies of SSH vs. HTTPS push should be explained (or linked).

As I already wrote the rest of the Getting Started guide, I could continue on this in the same tone. Or someone else wants to do this, which is fine too! :)

While Knut-ifying the images (see #55), I noticed that the "First Repository" article could use some more details. I'm thinking of guiding a user who had no prior exposure to Git to creating a repository and pushing it to Codeberg. Right now the guide ends at creating an `origin` remote. It would be nice to add a first commit+push in a step-by-step way. Also the intricacies of SSH vs. HTTPS push should be explained (or linked). As I already wrote the rest of the Getting Started guide, I could continue on this in the same tone. Or someone else wants to do this, which is fine too! :)

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

GitHub developed some really nice guides to get started: https://guides.github.com/
I don't think it even makes sense to try to "copy" them, but since the workflows are all similar (because it's all Git), I would recommend linking to them.

One thing that could be added to the "Getting Started" guide is how to add collaborators to a repo.

GitHub developed some really nice guides to get started: https://guides.github.com/ I don't think it even makes sense to try to "copy" them, but since the workflows are all similar (because it's all Git), I would recommend linking to them. One thing that could be added to the "Getting Started" guide is how to add collaborators to a repo.

lhinderberger commented 2020年09月16日 17:38:21 +02:00

I think it would be rather awkward to link to non-free content of a page that we want to be an alternative to 😉

Besides its main purpose of teaching new users how to use Codeberg, I think the Getting Started guide can also serve the side purpose of welcoming new users with a bit of "character" / brand building :)

Adding collaborators to a repo could also fit well into the "Collaborating with Others" section.

I think it would be rather awkward to link to non-free content of a page that we want to be an alternative to :wink: Besides its main purpose of teaching new users how to use Codeberg, I think the Getting Started guide can also serve the side purpose of welcoming new users with a bit of "character" / brand building :) Adding collaborators to a repo could also fit well into the "Collaborating with Others" section.

ivan-paleo commented 2020年09月17日 08:33:01 +02:00

I think it would be rather awkward to link to non-free content of a page that we want to be an alternative to 😉

I see what you mean and I also agree. Still, these guides really helped me and they are really well made. At least, we should get "inspiration" from them

Besides its main purpose of teaching new users how to use Codeberg, I think the Getting Started guide can also serve the side purpose of welcoming new users with a bit of "character" / brand building :)

Adding collaborators to a repo could also fit well into the "Collaborating with Others" section.

+1

> I think it would be rather awkward to link to non-free content of a page that we want to be an alternative to :wink: I see what you mean and I also agree. Still, these guides really helped me and they are really well made. At least, we should get "inspiration" from them > Besides its main purpose of teaching new users how to use Codeberg, I think the Getting Started guide can also serve the side purpose of welcoming new users with a bit of "character" / brand building :) > > Adding collaborators to a repo could also fit well into the "Collaborating with Others" section. +1

ivan-paleo commented 2020年09月17日 15:48:24 +02:00

Adding collaborators to a repo could also fit well into the "Collaborating with Others" section.

How do I add a new subsection to the Documentation? I know how to edit a file, but I'm not sure about the best way to create a new file/subsection, especially regarding the eleventyNavigation header.

> Adding collaborators to a repo could also fit well into the "Collaborating with Others" section. How do I add a new subsection to the Documentation? I know how to edit a file, but I'm not sure about the best way to create a new file/subsection, especially regarding the `eleventyNavigation` header.

lhinderberger commented 2020年09月17日 18:40:48 +02:00

The eleventyNavigation header is what holds the structure of the site.

For a given subsection it can look like this:

---
eleventyNavigation:
 key: WhatIsCodeberg
 title: What is Codeberg?
 parent: GettingStarted
 order: 10
---

Every section and article/subsection has a unique key. If parent is set to the key of another section, the current document will become a subsection of that other section.

The other fields are title and order, where title is merely a display name and determines the menu entry label as well as the article's heading but has no other "technical" semantics and order is a number that can be used to enforce a specific order of subsections (which is good for step-by-step guides such as Getting Started for example).

So to create a new subsection, find the key of your desired parent section in its Markdown source code and use it as the parent for your new article/subsection.

The `eleventyNavigation` header is what holds the structure of the site. For a given subsection it can look like this: ``` --- eleventyNavigation: key: WhatIsCodeberg title: What is Codeberg? parent: GettingStarted order: 10 --- ``` Every section and article/subsection has a unique `key`. If `parent` is set to the `key` of another section, the current document will become a subsection of that other section. The other fields are `title` and `order`, where `title` is merely a display name and determines the menu entry label as well as the article's heading but has no other "technical" semantics and `order` is a number that can be used to enforce a specific order of subsections (which is good for step-by-step guides such as Getting Started for example). So to create a new subsection, find the `key` of your desired parent section in its Markdown source code and use it as the `parent` for your new article/subsection.

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

OK, it sounds easy enough, thank you for the detailed explanation :)

OK, it sounds easy enough, thank you for the detailed explanation :)

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

I think it would be rather awkward to link to non-free content of a page that we want to be an alternative to 😉

I see what you mean and I also agree. Still, these guides really helped me and they are really well made. At least, we should get "inspiration" from them

I would recommend adapting the following guides:

• Understanding the GitHub flow
• Forking Projects
• Mastering Issues
• Making Your Code Citable

I will write something about the last one (citable code), but I'm not confident enough about the content of the others.

> > I think it would be rather awkward to link to non-free content of a page that we want to be an alternative to :wink: > > I see what you mean and I also agree. Still, these guides really helped me and they are really well made. At least, we should get "inspiration" from them I would recommend adapting the following guides: * [Understanding the GitHub flow](https://guides.github.com/introduction/flow/) * [Forking Projects](https://guides.github.com/activities/forking/) * [Mastering Issues](https://guides.github.com/features/issues/) * [Making Your Code Citable](https://guides.github.com/activities/citable-code/) I will write something about the last one (citable code), but I'm not confident enough about the content of the others.

lhinderberger commented 2020年09月18日 22:52:55 +02:00

We should certainly write about all of these topics :)

I wasn't aware about citable code yet but I'm very curious about it - I'm looking forward to your article on this 👍 🚀

We should certainly write about all of these topics :) I wasn't aware about citable code yet but I'm very curious about it - I'm looking forward to your article on this 👍 🚀

n commented 2020年09月19日 07:29:29 +02:00

For citable code, does Zenodo integrate with Codeberg/Gitea?

For citable code, does Zenodo integrate with Codeberg/Gitea?

ivan-paleo commented 2020年09月19日 07:42:35 +02:00

For citable code, does Zenodo integrate with Codeberg/Gitea?

Unfortunately it doesn't. I'm not sure on which side the problem lies: Zenodo oder Codeberg/Gitea. Probably a bit of both.

The integration makes it easier and faster, but it is not necessary. It's all about links so they can be entered manually.

> For citable code, does Zenodo integrate with Codeberg/Gitea? Unfortunately it doesn't. I'm not sure on which side the problem lies: Zenodo oder Codeberg/Gitea. Probably a bit of both. The integration makes it easier and faster, but it is not necessary. It's all about links so they can be entered manually.

n commented 2020年09月20日 18:58:34 +02:00

Ah, so Zenodo would provide a DOI which would link to the Codeberg repo?

Ah, so Zenodo would provide a DOI which would link to the Codeberg repo?

ivan-paleo commented 2020年09月21日 08:39:18 +02:00

To give a bit more details on the Zenodo-GitHub integration:
Once the two accounts are linked, the user only needs to create a release of the GitHub repo. Then, everything is made automatically: the ZIP archive of the release is uploaded to Zenodo, it gets a DOI there and the information (repo URL, release date... - metadata so to say) is also added.
I also think that when you create a new release for your repo, Zenodo will create a new version of the record (rather than a new record) with a new DOI.
But there's nothing that cannot be done manually; it just takes more time.

The Zenodo help desk is really helpful; maybe it would make sense to contact them to see if they would be ready to accommodate for Codeberg. I could do that of course, but I believe it will get (too) technical pretty quickly.

To give a bit more details on the Zenodo-GitHub integration: Once the two accounts are linked, the user only needs to create a release of the GitHub repo. Then, everything is made automatically: the ZIP archive of the release is uploaded to Zenodo, it gets a DOI there and the information (repo URL, release date... - metadata so to say) is also added. I also think that when you create a new release for your repo, Zenodo will create a new version of the record (rather than a new record) with a new DOI. But there's nothing that cannot be done manually; it just takes more time. The Zenodo help desk is really helpful; maybe it would make sense to contact them to see if they would be ready to accommodate for Codeberg. I could do that of course, but I believe it will get (too) technical pretty quickly.

ivan-paleo commented 2020年09月21日 08:42:18 +02:00

So what I am writing for now is quite general when it comes to online repositories. As long as Codeberg does not integrate with any online repository, there is no point in choosing Zenodo over another one. This means I cannot give precise instructions, because it depends on the online repository chosen by the user.

But I still find such a documentation useful because it makes the whole DOI thing explicit, and it also mentions the releases. And it can always be expanded/edited as needed.

So what I am writing for now is quite general when it comes to online repositories. As long as Codeberg does not integrate with any online repository, there is no point in choosing Zenodo over another one. This means I cannot give precise instructions, because it depends on the online repository chosen by the user. But I still find such a documentation useful because it makes the whole DOI thing explicit, and it also mentions the releases. And it can always be expanded/edited as needed.

lhinderberger commented 2020年09月22日 01:13:09 +02:00

see if they would be ready to accommodate for Codeberg

You might be delighted by the fact that Zenodo are offering a REST API - So it should be possible build a handy little tool for that! :)

> see if they would be ready to accommodate for Codeberg You might be delighted by the fact that Zenodo are offering [a REST API](https://developers.zenodo.org/) - So it should be possible build a handy little tool for that! :)

ivan-paleo commented 2020年09月22日 08:32:33 +02:00

You might be delighted by the fact that Zenodo are offering a REST API - So it should be possible build a handy little tool for that! :)

Yes I am! I will soon be able to PR my article on that. And I will edit it as soon as there is an interface between Zenodo and Codeberg!
But I won't be able to deal with the interface myself, as you know XD

> You might be delighted by the fact that Zenodo are offering [a REST API](https://developers.zenodo.org/) - So it should be possible build a handy little tool for that! :) Yes I am! I will soon be able to PR my article on that. And I will edit it as soon as there is an interface between Zenodo and Codeberg! But I won't be able to deal with the interface myself, as you know XD

lhinderberger commented 2020年09月22日 14:55:08 +02:00

No problem :) It's an interesting side project and I'm sure there's someone who can realize it.

I am a bit time-constrained at the moment, otherwise I'd be interested to have a look at it.

Maybe @n has time for another side project? 😄

Otherwise we could also take the idea and put it up on Codeberg Issues for grabs.

No problem :) It's an interesting side project and I'm sure there's someone who can realize it. I am a bit time-constrained at the moment, otherwise I'd be interested to have a look at it. Maybe @n has time for another side project? :smile: Otherwise we could also take the idea and put it up on Codeberg Issues for grabs.

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

I have added an article on making your code citable (see #81).

I have added an article on making your code citable (see #81).

ivan-paleo commented 2020年09月24日 09:44:54 +02:00

Adding collaborators to a repo could also fit well into the "Collaborating with Others" section.

PR #82

> Adding collaborators to a repo could also fit well into the "Collaborating with Others" section. PR #82

lhinderberger commented 2020年09月26日 14:13:47 +02:00

The full extended First Repository article is now ready for review and merge in #79

The full extended First Repository article is now ready for review and merge in #79

lhinderberger commented 2020年10月05日 00:05:32 +02:00

With #79 merged, this can now be closed.

With #79 merged, this can now be closed.