Extend "First Repository" article #56

Closed
opened 2 years ago by lhinderberger · 20 comments

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! :)
lhinderberger added the
Status: Needs feedback
Kind: Documentation
Kind: Enhancement
labels 2 years ago

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

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.

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

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

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.

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

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

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:

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

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 2 years ago
Collaborator

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

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

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 2 years ago
Collaborator

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?

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.

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

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

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
Poster

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.

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

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

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

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
Poster

With #79 merged, this can now be closed.

With #79 merged, this can now be closed.
lhinderberger closed this issue 2 years ago
Sign in to join this conversation.
No Milestone
No Assignees
3 Participants
Notifications
Due Date

No due date set.

Dependencies

This issue currently doesn't have any dependencies.

Loading…
There is no content yet.