Getting Started Guide (#47)

Basics of Issue Tracking

A basic Getting Started Guide

Reviewed-on: https://codeberg.org/Codeberg/Documentation/pulls/47

LICENSE.md

@@ -8,4 +8,6 @@ looked up in [https://codeberg.org/Codeberg/Documentation/commits/branch/master]
 The Codeberg logos in this website are by mray,
 licensed under [CC-BY 4.0](https://creativecommons.org/licenses/by/4.0/deed.en).
 
-Codeberg and the Codeberg Logo are trademarks of Codeberg e.V.
+Codeberg and the Codeberg Logo are trademarks of Codeberg e.V.
+
+"Knut the Polar Bear" has been derived from https://openclipart.org/detail/193243/polar-bear-remix, under CC0 1.0

assets/images/getting-started/knut.svg

@@ -0,0 +1 @@
+<svg id="Layer_1" width="56.7" height="56.7" enable-background="new 0 0 246.996 333.724" version="1.0" viewBox="0 0 56.7 56.7" xmlns="http://www.w3.org/2000/svg" xmlns:cc="http://creativecommons.org/ns#" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"><g id="g4215" transform="matrix(.983 0 0 .983 -18.5 -.00116)"><path id="path2479" d="m27.3 0.774c-4.27 0-7.73 3.46-7.73 7.73 0 2.76 1.45 5.18 3.63 6.55-2.3 4.07-3.63 8.77-3.63 13.8 0 15.5 12.6 28.1 28 28.1s28.1-12.6 28.1-28.1c0-5.01-1.33-9.71-3.63-13.8 2.17-1.37 3.63-3.79 3.63-6.55 0-4.27-3.46-7.73-7.73-7.73-2.76 0-5.17 1.45-6.54 3.63-4.08-2.31-8.78-3.63-13.8-3.63-5.01 0-9.71 1.32-13.8 3.63-1.37-2.18-3.78-3.63-6.54-3.63z" fill="#fff" stroke="#010101" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.54"/><path id="path3192" d="m41.5 34.7c2.01-2.15 10.5-2.16 12.3 0.268 1.79 2.3-2.68 8.85-6.17 8.58-3.48-0.266-8.06-6.84-6.17-8.85z" fill="#010101"/><g id="g291" transform="matrix(.386 0 0 .386 -90.3 -138)"><path id="path3179" d="m409 417c0 11.3-9.16 20.5-20.5 20.5s-20.5-9.16-20.5-20.5 9.16-20.5 20.5-20.5 20.5 9.16 20.5 20.5z" fill="#fff" stroke="#010101" stroke-linecap="round" stroke-linejoin="round" stroke-width="3"/><path id="path3183" d="m390 421c0 3.65-2.96 6.61-6.61 6.61s-6.61-2.96-6.61-6.61 2.96-6.61 6.61-6.61 6.61 2.96 6.61 6.61z" fill="#010101"/></g><path id="path3177" d="m43.8 23.3c0 4.36-3.53 7.89-7.89 7.89-4.36 0-7.89-3.53-7.89-7.89s3.53-7.89 7.89-7.89c4.36 0 7.89 3.53 7.89 7.89z" fill="#fff" stroke="#010101" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.16"/><path id="path2515" d="m40.8 24.8c0 1.41-1.14 2.55-2.55 2.55s-2.55-1.14-2.55-2.55c0-1.41 1.14-2.55 2.55-2.55s2.55 1.14 2.55 2.55z" fill="#010101"/><path id="path2525" d="m73.7 18.5c0.286 1.6 0.434 3.25 0.434 4.93 0 15.5-12.6 28.1-28.1 28.1-11.8 0-21.9-7.33-26.1-17.7 2.35 13.1 13.8 23.1 27.6 23.1 15.5 0 28.1-12.6 28.1-28.1-0.0039-3.65-0.706-7.13-1.98-10.3z" fill="#010101" fill-opacity=".314"/><g id="g300" transform="matrix(.386 0 0 .386 -93.4 -138)" fill="#666"><path id="path2483" d="m418 368c-4.02 0-7.52 2.12-9.53 5.28 6.14 4.14 11.4 9.42 15.6 15.6 3.15-2 5.26-5.54 5.26-9.55 0-6.24-5.07-11.3-11.3-11.3z"/><path id="path2523" d="m313 368c4.02 0 7.53 2.12 9.53 5.28-6.14 4.14-11.4 9.42-15.6 15.6-3.15-2-5.26-5.54-5.26-9.55-0.01-6.24 5.05-11.3 11.3-11.3z"/></g></g><metadata id="metadata39"><rdf:RDF><cc:Work><dc:format>image/svg+xml</dc:format><dc:type rdf:resource="http://purl.org/dc/dcmitype/StillImage"/><cc:license rdf:resource="http://creativecommons.org/publicdomain/zero/1.0/"/><dc:publisher><cc:Agent rdf:about="http://openclipart.org/"><dc:title>Openclipart</dc:title></cc:Agent></dc:publisher><dc:title/></cc:Work><cc:License rdf:about="http://creativecommons.org/publicdomain/zero/1.0/"><cc:permits rdf:resource="http://creativecommons.org/ns#Reproduction"/><cc:permits rdf:resource="http://creativecommons.org/ns#Distribution"/><cc:permits rdf:resource="http://creativecommons.org/ns#DerivativeWorks"/></cc:License></rdf:RDF></metadata></svg>

content/collaborating/index.md

@@ -6,5 +6,9 @@ eleventyNavigation:
   order: 30
 ---
 
-These documentation pages contain information on how you can collaborate on Codeberg,
-for example [by making Pull Requests](/collaborating/pull-requests-and-git-flow).
+These documentation pages contain detailed information on how you can collaborate 
+on Codeberg, for example [by making Pull Requests](/collaborating/pull-requests-and-git-flow).
+
+If you're new to Codeberg or software forges in general, please also have a look at
+our [Getting Started Guide](/getting-started) which will teach you the basics of
+issue tracking and wikis on Codeberg.

content/getting-started/creating-account.md

@@ -1,8 +0,0 @@
----
-eleventyNavigation:
-  key: CreatingAccount
-  title: Creating an Account
-  parent: GettingStarted
-  order: 20
-  draft: true
----

content/getting-started/first-steps.md

@@ -0,0 +1,71 @@
+---
+eleventyNavigation:
+  key: FirstSteps
+  title: Your First Steps on Codeberg
+  parent: GettingStarted
+  order: 20
+---
+
+## Registering at Codeberg.org
+<picture>
+  <source srcset="/assets/images/getting-started/first-steps/register.webp" type="image/webp">
+  <img src="/assets/images/getting-started/first-steps/register.png" alt="Register">
+</picture>
+
+To create your account at Codeberg.org, visit [https://codeberg.org](https://codeberg.org)
+and click on "Register" to bring up the registration form.
+
+There, simply fill in your username and email address and then choose a good password.
+
+After confirming your email address by clicking the link that we sent you to your 
+email account, you're done and good to go!
+
+
+## Community
+Codeberg is a non-profit volunteer effort. It relies on its friendly and dedicated community. We're happy that you're now a part of our community, too, and we hope you're feeling welcome!
+
+We kindly ask you to be polite and civil when on Codeberg and to not excessively use the resources provided. Please see our [Terms of Use](https://codeberg.org/codeberg/org/src/branch/master/TermsOfUse.md) for details. 
+
+Please remember that everyone here is contributing on their free time, as volunteers.
+
+If you like a project on Codeberg, consider **giving it a star** and/or **following its author**. That helps building and growing a network of free software projects and people and can serve as guidance for users exploring Codeberg, looking for interesting projects to try out or contribute to.
+
+
+## Orienting yourself on Codeberg
+After successfully registering on Codeberg, you should see this screen:
+
+<picture>
+  <source srcset="/assets/images/getting-started/first-steps/dashboard.webp" type="image/webp">
+  <img src="/assets/images/getting-started/first-steps/dashboard.png" alt="Dashboard">
+</picture>
+
+An explanation of the highlighted elements above:
+
+- **Dashboard (1)** is the screen you're looking at right now. It gives you an overview of the newest activity
+  of you, the people you follow and in your or your organization's projects.
+- **Issues (2)** and **Pull Requests (3)** These are overviews of issues and pull requests that you are either involved in or that are part of one of the organizations you belong to.
+- **Codeberg Issues (4)** This is currently the primary communication channel for the Codeberg Community. Here, you can ask questions, report bugs and suggest changes to Codeberg. You're also welcome to browse these issues and contribute your solutions, if you want to support Codeberg even more.
+- **The Create Menu (5)** You can create repositories, organizations and migrations using this menu. It's your entry point to kicking off entirely new things on Codeberg.
+- **Your Avatar (6)** will lead you to a menu, where you can look at your profile, edit your settings, view the documentation of Gitea (the software Codeberg is based on) or log out.
+- **The Dashboard Context Switcher (7)** If you're part of one or more organizations, you can use this context switcher to let the dashboard display information relevant to the organization, rather than your account.
+
+
+## A word about Security
+While it is important to choose a strong password, it is also
+important to use Two-factor Authentication in case your password or device
+ever gets compromised, so that should be one of the first things to 
+configure after you have created your account.
+
+We recommend that you use Two-factor Authentication on your account, to increase
+your security.
+
+> Please visit the [guide in the security section](/security/2fa) to learn how to set up 2FA.
+
+
+## Moving on from here
+Now that you have an account on Codeberg.org, you can choose from a number of possible ways to explore:
+
+- [Create your first Repository](/getting-started/first-repository)
+- [Report or Comment on an Issue](/getting-started/issue-tracking-basics)
+- [Learn how to use Git](/git) and then [Contribute a Pull Request](/collaborating/pull-requests-and-git-flow)
+- [Contribute to Codeberg](/improving-codeberg)

content/getting-started/index.md

@@ -6,12 +6,14 @@ eleventyNavigation:
   order: 10
 description: This article shows you how to get started with Codeberg
 ---
+<img src="/assets/images/getting-started/knut.svg" style="float: right; width: 150px; border: none; margin-left: 25px; margin-bottom: 25px;" alt="Knut the Polar Bear">
 
 Hello there!
 
-We're glad you're considering to join [Codeberg, the community-driven non-profit
-software development platform](/getting-started/what-is-codeberg).
+We're glad you're considering to join Codeberg, the <span style="white-space: nowrap;">community-driven</span> <span style="white-space: nowrap;">non-profit</span> software development platform.
 
-These pages will guide you through your first steps on Codeberg.
+I'm Knut the Polar Bear, and I'm going to guide you through your first steps on Codeberg.
 
-You can start with [creating an account](/getting-started/creating-account). If you already have an account, please continue with [creating your first repository](/getting-started/first-repository).
+You can start with [finding out more about Codeberg](/getting-started/what-is-codeberg) or by jumping right to [your first steps on Codeberg](/getting-started/first-steps).
+
+Welcome to Codeberg! 😊

content/getting-started/issue-tracking-basics.md

@@ -0,0 +1,99 @@
+---
+eleventyNavigation:
+  key: IssueTrackingBasics
+  title: The Basics of Issue Tracking
+  parent: GettingStarted
+  order: 40
+---
+
+Issues are an important mean of communication on Codeberg.
+Besides their original purpose - reporting bugs to a project's maintainer -
+they can be used to suggest enhancements, ask for new features, discuss a project's
+direction, ask questions and much more.
+
+### The Issue Tracker
+<picture>
+  <source srcset="/assets/images/getting-started/issue-tracking-basics/issues-list.webp" type="image/webp">
+  <img src="/assets/images/getting-started/issue-tracking-basics/issues-list.png" alt="Issues List">
+</picture>
+
+You can find the issue tracker of a project by clicking its "Issues" tab (1).
+
+There, you will see browseable and filterable (2) list of all issues.
+Many projects use labels to categorize issues. A good label to look for, if you want
+to contribute to a project is the "help wanted" label.
+
+You can switch between issues that are still open, and those that are already resolved (3).
+
+Some projects define milestones (4), to which issues can be assigned. They are good for
+visualizing the high-level progress of a project's development.
+
+You can create an issue by clicking on the green "New Issue" button (5) at the top left 
+of the issues list.
+
+Issues in the issue tracker are public and everyone is able to read and answer to them.
+
+An Issue can have an assignee, meaning someone responsible for resolving or moderating
+the issue. Their profile picture, with a link to their profile, can be seen in the issue 
+list.
+
+### Life of an Issue
+Once an Issue in the Issue Tracker has been created, it will usually pass through a
+process of review, discussion and closure, which is sometimes more, sometimes less
+strictly defined, based on the project you're contributing to.
+
+The first thing that might happen is that your issue is categorized using labels.
+Your issue may be reviewed by the project's maintainer(s) and evaluated whether it i.e. might be a duplicate or an invalid bug report.
+
+Then, depending on what kind of issue it is, there might be a additional questions
+or a discussion and, if applicable, the implementation of a solution (or the rejection of 
+the issue).
+
+Finally, the issue is closed, thus vanishing from the list of open issues.
+Issues might have dependencies on other issues or pull requests preventing them from being closed.
+
+Occasionally, issues might become stale. That's when there hasn't been any progress for
+an extended period of time (usually months). You might consider reviving these, if there
+is a strong interest in getting them resolved (and, preferably,  if you can contribute 
+something to them).
+
+> If you encounter an abandoned project and there is no way to contact the maintainer(s),
+> consider forking it, if you want to assume responsibility for it (or, rather, your fork).
+
+### Things to consider
+#### Security bugs
+If the bug you have found has security implications, **do not create
+an issue right away!**. Instead try contacting the project's maintainers privately.
+Many projects have a dedicated e-mail-address for reporting security bugs. If the
+project in question doesn't, consider writing an email directly to the project's 
+maintainer or ask for the address in the issue tracker.
+ 
+> **⚠** What's important is that you **don't publicly expose security bugs before they are
+> fixed *and* the fixes are deployed** because **otherwise you might put the users of that
+> project at severe risk**.
+
+#### Existing issues
+Before creating a new issue, please make sure that there isn't already an existing
+issue covering i.e. the bug that you want to report or the feature that you want to
+request.
+
+If there already is an existing issue, please consider commenting that issue instead,
+if there is something more that you can contribute to it.
+
+You should also make sure that the issue has not already been solved by having a look
+the closed issues (3) as well.
+
+#### Try to be precise and helpful
+Project maintainers love precise information about why i.e. a bug is happening.
+
+Some projects may even have templates that specifically ask for information like
+the operating system or database software used.
+
+If you can provide that information, it will be easier for the project maintainer(s)
+to quickly resolve your issue. And if you want it resolved even quicker,
+consider writing a Pull Request solving the issue (if possible).
+
+#### Be (reasonably) patient
+Please remember that many project maintainers work on their free software projects
+in their free time. Some maintainers may answer you within minutes, others within days.
+Don't be discouraged if there isn't an immediate answer.

content/getting-started/what-is-codeberg.md

@@ -4,5 +4,26 @@ eleventyNavigation:
   title: What is Codeberg?
   parent: GettingStarted
   order: 10
-  draft: true
 ---
+
+Codeberg is a community-driven, non-profit software development platform operated
+by Codeberg e.V. and centered around Codeberg.org, a Gitea-based software forge.
+
+On Codeberg you can develop your own [Free Software](https://simple.wikipedia.org/wiki/Free_software) projects, contribute to other
+projects, [browse](https://codeberg.org/explore) through inspiring and useful
+free software, share your knowledge or build your projects a home in the web
+using [Codeberg Pages](/codeberg-pages), just to name a few.
+
+Codeberg is not a corporation but a community of free software enthusiasts providing
+a humane, non-commercial and privacy-friendly alternative to commercial services
+such as GitHub.
+
+Codeberg e.V. is a registered association based in Berlin, Germany. You don't have to be
+a member of the association in order to join Codeberg.org or to contribute to the development
+of the platform, but if you want you can [join Codeberg e.V.](https://join.codeberg.org) to
+support the project financially, be informed about Codeberg and, optionally, to actively
+contribute to the association.
+
+<br>&nbsp;
+
+To start your journey with Codeberg, let's [create an account](/getting-started/first-steps).

content/getting-started/wiki-basics.md

@@ -0,0 +1,8 @@
+---
+eleventyNavigation:
+  key: WikiBasics
+  title: Contributing to Wikis
+  parent: GettingStarted
+  order: 50
+  draft: true
+---

content/home.md

@@ -5,4 +5,4 @@ Welcome to the Codeberg Documentation pages!
 
 Please choose a section from the menu on the left.
 
-If you're new to Codeberg, consider starting at [Getting Started](/getting-started).
+If you're new to Codeberg, consider reading the [Getting Started Guide](/getting-started).