DEV Community: Francesco Sardone

Understanding GitHub Pull Requests

Francesco Sardone — Mon, 16 Oct 2023 06:00:00 +0000

Introduction
Requirements
Overview
Pull Requests
Navigating Request
Conclusion
Share Support

Introduction

Hey there! I'm Francesco known as Airscript on the web.
Today we're gonna continue our focus on GitHub Repositories taking a look to Pull Requests tab.
Without any further ado, I think we can start.

Requirements

You don't need any particular requirement to consult pull requests section on GitHub.
If you need a place to follow along this post, my chosen repository for today's blog post is Beelzebub.

Overview

I will start this post with a simple question: have you ever wondered how you can actually contribute to a software project?
Probably now in your mind you have something like: "Writing code, of course!"
That is totally right, but how? How do you represent and share that block of code that you wrote?
That is done by making a pull request!

Pull Requests

So, let's deep dive on what is a pull request first.
As we have seen in the overview section, a pull request, for short PR, is actually a request for making a change inside a software.
Those changes are detected as additions and removals and usually they look like this:

In green we see additions and in red removals.

Unlike issues, pull requests can have more than two states.
A pull request can be seen as open, closed and merged. In some cases also as draft.
Let's see what they mean:

An open pull request means that a contributor just has expressed the willingness to contribute to a project, making some changes;
A closed pull request means that the pull request has come to an end, without being merged inside the repository;
A merged pull request means that our contribution has seen light and now it is part of the software project itself;
A draft pull request means that it is not ready to be reviewed and merged.

As a last note, pull requests like issues can be labeled and added to milestones.
So, everything we told about those two entities in this previous blog post is totally right also for pull requests!

Navigating Requests

Now that we are experts of what a pull request actually means, let's see where we can find them and how we can filter them out.
While over our selected GitHub repository, let's just take a look on the top left portion of our screen:

As indicated inside the image above, we can simply select Pull Requests and jump inside this wonderful world:

I've filtered out for closed ones since there were no open requests at the time of this blog post.

This is where all the pull requests lie.
And just like issues themselves, we can use fast filters for searching whatever we are looking for in a rapid fashion as well as just searching for keywords inside the search bar!

Bonus

Now that you know what is a pull request and where you can find it, if you're looking for making your own first pull request just make sure to drop off my blog post on how to make your first pull request!

Conclusion

In today's blog post we have seen what is a pull request, how many states it can have and where we can find and filter them out in GitHub.
At this point with the knowledge acquired with this series, you are already able to create your own project, open issues and resolve them via pull request.
Be proud of yourself!

Share Support

If you have liked this post, just leave a reaction and a comment in the section below.
To not lose any new post, just remember that you can follow me here on dev.to and also other platforms that you can find on airscript.it.
Thank you kindly!

Patreon Meets GitHub Sponsors

Francesco Sardone — Mon, 09 Oct 2023 06:00:00 +0000

Introduction
Requirements
Overview
Connecting Patreon
Bonus
Conclusion
Share Support

Introduction

Hey there! I'm Francesco known as Airscript on the web.
Today we're gonna see how to connect Patreon to our GitHub Sponsors profile.
This possibility to interconnect these two services has been launched a few days ago from the publishment of this post, so I thought it would be awesome to see how it can be done.

Requirements

In order to proceed with this post, you'll need two things:

A personal GitHub Sponsors profile;
A personal Patreon profile;

Overview

This event, happened between GitHub Sponsors and Patreon, marks a new milestone in open source empowerment.
One thing that we suffer inside our ecosystem is the possibility to give something back to those marvelous contributors, who gift everyday their time for our own pledge.

Having Patreon it's not only an additional service to give credit, but this credit can be shown up over our GitHub profile too!

Now without investing more words on the matter, let's see how we can connect everything.

Connecting Patreon

Let's start heading to our GitHub profile.

Here we can simply click onto Sponsors Dashboard and reach this section after that:

You can find this at the left of the page.
Just click onto Settings to reach our final stop for connecting Patreon:

Simply click Connect with Patreon and allow Patreon to connect with your GitHub Profile:

If everything goes as expected, you'll be redirected to your GitHub Sponsors with this marvelous message appearing before your eyes:

And that's all, we did it!
Now we can see who sponsors us on Patreon also onto GitHub Sponsors!

Bonus

If you want to allow people to sponsor you through Patreon via GitHub Sponsors, there is a small step to do.
Just go again inside your Settings section and tick this functionality:

After selecting this, inside your sponsor page, you'll see a new tab leading to Patreon and its tiers:

Conclusion

In today's post we have seen how to connect Patreon with GitHub Sponsors.
Don't forget to donate even a single dollar to your most ispirational open contributors out there.
Tell them that they are meaningful for you!

Share Support

No More Problems With GitHub Issues

Francesco Sardone — Mon, 02 Oct 2023 06:00:00 +0000

Introduction
Requirements
Overview
Issues
Labels
Milestones
Conclusion
Share Support

Introduction

Hey there! I'm Francesco known as Airscript on the web.
Today we're gonna continue our focus on GitHub Repositories taking a look to Issues tab.
Without any further ado, I think we can start.

Requirements

You don't need any particular requirement to consult issues section on GitHub.
If you need a place to follow along this post, my chosen repository for today's blog post is Awesome.

Overview

Let's say you have encountered problems with a particular software that you're using and that software is also available on GitHub. How do you check an open issue or report one?
That's what we'll be learning today!

It can be daunting at first, looking at this image, to know what's going on. Fear not, there are three main things to learn here: issues, labels and milestones.

Issues

Starting from the roots, an issue as the name implies, is a problem.
During the years this term just evolved in something more, even though not matching its meaning.
Today's issues are simply activities. Activities that can span from features, discussions, ideas, bugs and so on.
One important thing to keep in mind for issues is that they can have, talking simply, two states: open and close state.

Inside of GitHub you can create, search or simply interact with issues.

Creating An Issue

So starting from here, what do I have to do to start creating a new issue?
It's simple. Just use the green button on the right and fill the information needed in the opening page:

Remember that this is not an in-depth article on issues lifecycle , but an overview on issues tab in GitHub.

Searching An Issue

In order to fulfill the search of an issue, we have a pretty long search bar in this section.
And, the cool thing about this bar, is that it just responds to its search language.

In this image, we are filtering for opened issues.

Interacting With An Issue

The last thing that we can do, regarding issues in this section, it to click on them and actually interacting with them.
As you see, there is a list in the first image representing, of course, the listed issues for the repository.
When clicking on one of them, you are entering the deep context of it, looking at title, descriptions, comments and so on.
You can also leave a comment of yours if you want to!

Labels

Now that we have seen what issues are and what we can do with them, specifically to this section, let's talk about labels.

Labels serve different purposes but the main one is to categorize issues.
GitHub on every new repository just creates some default ones such as: enhancement, documentation, bug and so on.

Don't forget to put a label on your issue if you want to get recognized for what it really is!

Milestones

At last only milestones remain.

Milestones are something that you don't want to sleep on.
They can be a container for issues, regarding a specific goal.
Let's do an example on this. Let's say that you file an issue for a project that you use and want to know when that issue will be solved.
Milestones tell you exactly that, even though not everyone uses them in the right way.
If your issue is listed inside a milestone that will be marked as the next version of the software, then you're good to go!

Here, following, an image representing a list of milestones.

Had to take this one onto another repository since Awesome is not using milestones currently.

Conclusion

In today's post we have seen Issues section inside a GitHub Repository.
We have talked about how to create, search and interact with issues as well as the meaning behind labels and milestones.
As you can see, things are starting to get a little bit complicated but don't worry: we still have time to talk in depth about issues, labeling, milestones and so on in later specific posts.

Share Support

Navigating Code In GitHub Repositories

Francesco Sardone — Mon, 25 Sep 2023 06:00:00 +0000

Introduction
Requirements
Header
Files
About
Releases
README
Conclusion
Share Support

Introduction

Hey there! I'm Francesco known as Airscript on the web.
Today we're gonna continue our focus on GitHub Repositories taking a look to Code tab.
Without any further ado, I think we can start.

Requirements

You don't need any particular requirement to consult code section on GitHub.

Header

Since we're going to do a deep dive on this topic, let's start from the top.
For the purpose of this blog post, I'll be using Awesome Steam Deck as reference.

Open the link and start with me from the left, just below the code tab:

In the case of this repository we have three main aspects:

Title: the actual name of repository;
Template: the base template from where it was generated;
Visibility: in this case as public, means it can be seen by everyone.

Going right, instead, we start to see something specific to GitHub itself:

Just looking at them in order, from left to right:

Sponsor: on GitHub repositories or users can be funded through GitHub Sponsors and this button serves that purpose;
Pin/Unpin: if you want to showreel you work, you can pin it on your profile page to make it stand thanks to this button;
Watch/Unwatch: when you're interested by a project, you can watch it and get all the updates from it such as releases and more;
Fork: the concept of fork is literally to make a copy of a repository on your profile or organization;
Star/Starred: a star is something that usually makes GitHub users happy and you can refer to it as a bookmark telling that you like it.

Files

After the header we can move out together inside the hot part of a repository: files.
Inside files we can check the actual code, documentation and more.
The whole project, basically.

Starting from the top, we see a selector for both branches and tags, but what are they?
Simply put, branches can be seen like different versions of a project that can be identical or flow in a different pathway just like a tree branch.
Tags have a similar concept but they're literally a photo of a branch on a specific period in time. Yes, just the selfie you made yourself years ago.
Other than this, on the right you see utilities for searching files, creating new ones and also different possibilities to code on your own.

Leaving behind the top part, we can go directly to the files tree.
This tree shows two main things:

Who made the last changes to the repository's code;
The files that compose up the repository.

Before moving onto the right portion of this page, I have to make a small focus onto the changes.
When you make a change to repository's code, that change is being called a commit.

About

Moving forward and for forward I mean to the right, we can see the About section.
Treat this as a recap section with all the useful information and metrics about a repository:

Aside all the information that we have already seen in the previous sections, a mention of honor goes to the software license, the various policies and the README of which we'll be talking in a few words.

Releases

The last section that we'll be covering from the right part is the one for Releases.
One thing that I've seen during my travels in the web, is that both technical and non-technical people will, from time to time, reach this section.

The reason is simple: it contains the actual software and usually you can download it from there.

README

The last part that we'll see in this post, is the famous README.

This section is one of the most useful inside a repository.
It tells you what does the project, how you can use it or how you can even contribute to it.
Look always for this section because it makes things clear about what you're looking to!

Conclusion

And we reached the end also for this blog post.
We have seen from top to bottom how a repository is organized, how to read and interpret all the fancy words it has in it and so on.

As a side note, a GitHub Repository is fulfilled of things that may be or not be there, so I made sure to treat only visible sections.
My wish is that you would go out there and discover them out by yourself. Now you have the knowledge to look up at repositories, after all!

Share Support

Creating A New GitHub Repository

Francesco Sardone — Mon, 18 Sep 2023 06:00:00 +0000

Introduction
Requirements
Creating A Repository
Repository Tabs
Conclusion
Share Support

Introduction

Hey there! I'm Francesco known as Airscript on the web.
Today I want to share with you how you can create a new GitHub Repository and navigate into it.
This post will serve us well for the next weeks while we'll be going deeper into the concepts behind repositories.

Requirements

In order to create a GitHub Repository you'll need a GitHub Account.

Creating A Repository

Now that you've checked all the requirements, just head to github.com and look at the top right portion of the screen.
There you'll see a button with a plus sign that makes wonders:

After clicking on New Repository, something like this one will appear in front of you:

First of all you'll be asked for a template repository.
A template repository is an already setup repository that will just work as a blueprint.
After that you'll have to choose the owner, a repository name and description.
Fill it out with whatever you want or use the funny suggestions that GitHub does for you!

Now let's go deeper onto the next steps and see what they mean:

You'll be asking yourself: "What is a README or even a license?"
Good question! A README is a simple text file where you can describe your repository starting from what does it address, to how you can use it and also how to contribute to it.

The license, on the other side, is also a file that contains a contract for protecting your rights regarding the software you're creating.
If you choose to not have one, the software you're making will not be freely usable like usually an open source software can.
If you want to make your own ideas on this matter, jump by choosealicense.com or wait for my series on the matter.

Of course I'm not forgetting about .gitignore.
This is a simple file that takes track of which files are not welcomed inside your repository.
If you have a personal file that you don't want to commit publicly then you just add its name inside of it and the magic is done.

After you've setup everything just click onto Create repository and the mission will be completed!

Repository Tabs

Now that you have created your repository, you'll see something like this:

Yes, I know. There's a lot of stuff right in front of us but fear not! I'm here.
As a first stepping stone let's see the various tabs inside of it and what they mean:

Right know we are into the Code section.
In this section you can actually see the code of your software and other useful information such as topics, websites and more.

Right after that, there's Issues tab where all issues are stored.
An issue can be a lot of things but explained simply, it's a tool to track down things about your repository.
e.g. Your software has an error while doing something? Fine, that's an issue to be opened.

Next to the issues tab there is a Pull Requests tab that also stores them.
This one is practically the heart of open source if you ask me.
Basically, if I want to contribute to a software, I make my own magic with code and then send it back to the original repository as a pull request.

Actions tab is a cool one. A little bit more advanced but nothing impossible to understand.
Let's think about something you do everyday, like brushing your teeths.
The key question here is: "Can you automate it?" and if the answer is yes, then you can represent it with the use of a reusable action!
Inside this tab you'll find all the actions and all the reports for every action that has been runned in the past.

Following this, there's Projects tab.
It speaks by itself but, you can see projects like big boards where you can track down things to do over your software.
This is a cool collaboration and management tool that GitHub gives for managing issues as well!

The Wiki tab is a good stop point for learning about the software itself.
Just imagine: you're a newcomer and don't know how things work. Where should you go to read about it? That's that place.

Now things start getting intresting with the Security tab.
This tab is essential if you want to keep track of vulnerabilities, updates, code improvements and so on. All automated for you with the ease of a simple click.

If you're a social person, we have also a tab for that side of you: Insights.
Here you have a lot of interesting information spacing between how many changes you did to the project to from where that contributor came inside your repository in the first place.

As last but not as least important we have the Settings tab.
This tab is the control panel for everything that just rotates around your repository.
e.g. Repository name, who can access it and more.

Conclusion

And I think we're good to go for now!
In the next posts we'll be seeing every tab in detail and also add some tabs that are hidden right after you create a project.
So, basically we have seen how to create a new repository and learned more about code licenses, README files and repository tabs.
As you can see behind a simple action, there is a lot more. But this is a good thing: means that you have a lot of space for self improvement!

Share Support

Adding Tools To Your GitHub Repositories

Francesco Sardone — Sun, 10 Sep 2023 15:57:05 +0000

Introduction
Requirements
Accessing The Marketplace
A Brief Overview
Integrating An App
Integrating An Action
Conclusion
Share Support

Introduction

Hey there! I'm Francesco known as Airscript on the web.
Today I want to share with you what is GitHub Marketplace and how you can use it for adding mainly tools to your repositories!

Requirements

In order to use GitHub Marketplace you'll need a personal GitHub account and preferably a repository where you can experiment all of this.

Accessing The Marketplace

In order to access the marketplace, go to your GitHub Dashboard while logged in, and select the hamburger menu in top left corner:

A sidebar will appear.
Just at the bottom of it, you'll see a marketplace entry:

Clicking it, you will reach GitHub Marketplace, where our adventure will take place.

A Brief Overview

Inside the marketplace we can practically select two different types of things: apps and actions.

They can be seen as almost the same thing: they just automate something and report back to you.
One of the key differences is that apps can act on their behalf.

Other than this, you can filter apps and actions by categories or their price.
No worries on that, most of the apps are regularly free for open source projects.

Integrating An App

After our brief introduction, I think it's time to start integrating stuff.
I've already selected one app, but feel free to experiment with your own needs and taste on that.
We'll try to integrate an image bot inside my blog repository:

Now just scroll down, select Open Source and click onto install:

The platform will ask you for a payment method but don't worry, the bot is free of cost, it's just a requirement.
Follow the steps and eventually you'll see something like this:

I've just selected one repository, but you can install over them all or wherever you want to.
Now that everything is setup, just click onto install again.
You'll be prompted for a password and then a screen like this will show up for giving the actual permissions:

Just remember: you're giving permissions on acting on your behalf to the apps that you're integrating.
Be sure of what you're installing or it can lead to serious security flaws.

Here we can click the authorization button and...

Now it's just a matter of time for receiving a pull request from our bot that is optimizing repo's images in a lossless fashion!

Integrating An Action

The other type of cool things that we can take from the marketplace are the actions.
Actions are simple workflows that automate something.
Instead of reinventing the wheel writing your own commands for running automated tests, for example, you can just check if there is an action already prepared for this reason and install it right away on your fabulous project.

Now, into the action. Same thing as before, let's go to the marketplace and select an action filtering by type.
For this post, I've selected a simple Action called First Interaction.
It simply greets a user on the first issue or pull request:

Click onto use latest version and copy the lines of code that it just gives you.
Go onto your repository on GitHub and create a .yml file inside a .github folder like this:

After that, just write on top of the explorer this string: .github/workflows/interaction.yml.
This is needed in order to create or point up to a folder.
The explorer I'm talking about it's something like this one:

And then, you can paste what we have actually copied.

Now, this is not enough because we're not telling the action the actual messages we want to display or, for example, on what kind of issues or pull requests it has to print them out.
Documentation comes in our help and every action has a usage section on their installation page:

So we'll just use the one from the example but a little bit more customization since it's missing all the environment's directives:

name: interaction

on:
  issues:
    types: [opened]

  pull_request:
    branches: [main]
    types: [opened]

jobs:
  interaction-checker:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - uses: actions/first-interaction@main

        with:
          repo-token: ${{ secrets.GITHUB_TOKEN }}

          issue-message: |
            Hey there! Thank you kindly for filing an issue.
            I'll reply back to you as soon as I can.

          pr-message: |
            Hey there! Thank you kindly for your contribution!
            I'll review back as soon as I can.

What I'm telling here is simply that I want to run this action only on opened issues and pull requests that are being made towards main branch.
The next thing I configured is the actual job that indicates the machine it'll be running on and the custom messages for both issues and pull requests.
Simple, isn't it?

Now we can simply commit everything and wait for someone to contribute to our project to see the magic!
In my case I've just asked @ilmanzo to open a test issue for me:

And this clears up the process on integrating also an action!

Conclusion

Today we have seen what is GitHub Marketplace and how to use it to integrate Apps and Actions as tools onto our repositories.
It may be challenging at first but don't give up!
Struggle is a sign of growth if you move toward it.

Share Support

If you have liked this post, just come and tell me!
Are you too shy for doing this? No problem. Just visit airscript.it and share your support following me on your preferred social platform.
If you want to make me even happier, just follow, share or star me and my projects on GitHub.

Discovering With GitHub Explore

Francesco Sardone — Sat, 02 Sep 2023 20:33:26 +0000

Introduction
Requirements
How To Access It
Explore
Topics
Trending
Collections
Events
GitHub Sponsors
Conclusion
Share Support

Introduction

Hey there! I'm Francesco known as Airscript on the web.
Today I want to share with you what is GitHub Explore and how you can use it for discovering magic things on it!

Requirements

In order to use GitHub Explore you don't need anything else except your browser.
I just recommend you make a personal GitHub account to take out the best out of it in terms of feeds.

How To Access It

In order to access Explore, we have different ways.
I'll just divide them by ease of access spacing from simple URL to the actual button inside the UI.

If you don't have an account on GitHub, the easiest way to reach it, it's by just simply going to https://github.com/explore:

The other way you can do it, it's via authenticated access.
While logged in, go to GitHub and on the bottom right portion you'll find something like this section:

Just click over Explore more and voilà, you're inside it.

Of course, there are other ways to go inside of it, but here we're listing only a few ways to do that.

Explore

Now that we know how to enter it, let's just look at Explore!
As we have seen in the other images in the previous section, we have a lot of things to check out.
In this section we'll be looking at Explore tab.
This specific part is useful for having a quick overview over everything we'll be seeing in other tabs.

At left we can see our starred topics, at the center the heart of Explore, i.e. repositories and on the right trending stuff.
Just by looking at this and scrolling you'll be finding, eventually, cool stuff to look over and try out!

An example of feed from Explore.

Topics

Let's imagine that you like a certain topic and you want to build a feed over it.
Instead of just cherry-picking best projects, GitHub Explore gives you the possibility to star a topic.
In this way you can have everything related to a topic straight up in your feeds without any effort!

Collections

Maybe you're just wondering that a topic cannot cover completely a specific theme or that a trending repository is only one about a big pool of things that concerns, for example, learning to code.
No worries on that! We got collections.

Collections, as the name suggests, are simply specific collections about a specific theme.
One example that comes to my mind is repositories made in your country and so on.

Events

This section is relevant to open source related events and here, if you like the subject, you can find something really amazing.
For example, in this period of time when I'm writing, GitHub itself is organizing GitHub Universe!

GitHub Sponsors

The last section is dedicated to GitHub Sponsors.
If you don't know what it is, it's simply the sponsor program made by GitHub in order to give value to developers contributing to open source.
We'll be making a deep focus on this matter, don't you worry.
Here you can practically check who's behind the libraries you use in your projects and eventually you can donate to them...and I highly suggest you do it.

Conclusion

So, we are at the end of this post from GitHub series.
We have checked how to access GitHub Explore, what are basically Explore, Topics, Trending, Collections, Events and GitHub Sponsors and what you can do with them!
If you integrate this tool in your dailies, I can assure you will find something that will change your life for the better.

Share Support

Making Your First Pull Request

Francesco Sardone — Sun, 27 Aug 2023 16:02:43 +0000

Introduction
Requirements
Searching For A Project
Forking
Making Your Changes
The Pull Request
Conclusion
Share Support

Introduction

Hey there! I'm Francesco known as Airscript on the web.
Today I want to share with you how you can contribute to an open source project making your first pull request to it!

Requirements

In order to make it, we'll use solely GitHub, since going into depth with tools and programming languages can be hard at first.
So the only requirement needed is an account on GitHub.

Searching For A Project

After you've got your GitHub account, we just need to search for a project to contribute to.
We have different options here: known projects, using the search bar, using the explore section and so on. It's really up to you.
If you're interested on how to do project scouting, let me know and I'll make a blog post specific to it.
For this blog post, I have chosen option A and so I'll be doing the pull request to a known project of a close connection.

Forking

The first action to do when contributing to open source projects, is to make a fork of the repository.
This comes true when you don't have direct push access to those repositories.
The fork process is easy to do as clicking a simple button on GitHub:

After clicking that button, GitHub will ask us where we want to place the repository and how we want to name it:

Let's keep everything as default and click the fork button.
Ta-da! Our first fork has been done.
Now the repository will be copied over the profile you have chosen.

Making Your Changes

Now that you did the fork, you got a copy of that project over your profile or the one that you've chosen to.
Because of this, we can just do our changes safely without worrying about being blocked for lack of permissions.
As I told you, this blog post just covers the basics of how you can do your first pull request taking out all the tech jargon you can from the process.
So even for our changes, we'll use GitHub's editor:

The edit option is placed on top right corner, just right when you select the file to be edited.
Clicking it, you'll just go inside the editor where you can make the changes.
After you have done that, we have to commit:

Clicking on commit changes will open a modal where we can choose a bunch of things:

Things like a commit title and description or the branch where we want to commit.
For the purpose of this post we want to choose main branch, like I did in this photo.
This help us cutting of the process of doing feature branching on our forked repository before doing the actual Pull Request to the project owner.
After clicking the green button, we are ready for opening our first Pull Request!

The Pull Request

Let's head back to our forked repository page and click onto the contribute button:

Here we can click onto the green button for opening the actual Pull Request and GitHub will just launch us towards a page like this one:

And after you've applied a title and a description to what you are changing, just click again the green button and ta-da! You made it!

Conclusion

In this blog post we actually have seen how to make our first pull request to our chosen open source project.
Bear in mind that we have actually looked only at the process and that in reality this can take up extra effort.
For example, the need to read how to contribute specifically to a project or, keeping behind the lifecycle of a pull request starting from change requests to failing pipelines.
I hope you have found this useful and if you want something deeper regarding this kind of topic, just reach me out!

Share Support

Multi Repository Documentation

Francesco Sardone — Sun, 20 Aug 2023 14:53:02 +0000

Introduction
Requirements
Setup
Wrapping Up
Conclusion
Share Support

Introduction

Hey there! I'm Francesco known as Airscript on the web.
Today I want to share with you how to use Antora, a tool for managing multi repository documentations.
In this blog post we'll see what's required to run an Antora project and how actually you can spin up one too!

Requirements

Before even starting the next section, be sure to have installed on your machine the following requirements:

Since we'll be using Antora 3, the suggested versions for Node.js runtime are spacing between 16 and 18 LTS.
Be sure to type node -v inside your terminal of choice to check which version you have.

Setup

After you got all the requirements, we can start making our multi repository documentation.
In this article I'll be covering a multi repository where we have split up the actual documentation and the UI used to present it.

UI

Let's start from the UI. In order to use it, we can just clone the base template offered by Antora:

$ git clone https://gitlab.com/antora/antora-ui-default.git documentation-ui

In this default UI, you'll find a folder structure comprehensible of various sections such as one for previewing your UI changes and so on.

After looking at the UI, we can practically move onto the actual repository for the documentation.
For this post we'll be using two demo documentations made by Antora, written in AsciiDoc.
You can simply modify those to your needs after all.

$ git clone https://gitlab.com/antora/demo/demo-component-a.git documentation-1
$ git clone https://gitlab.com/antora/demo/demo-component-b.git documentation-2

Now we have two documentations to add to our previously built UI.

Wrapping Up

Now that you have a fully scaffolded multi repository documentation, we have to wrap things up together.
Just for ease of use, we'll be making a dedicated repository that will contain the actual documentation holding both UI and contents.
In this repository we only need a playbook that will link everything up.
This playbook we'll be needed by antora CLI.
Let's start creating a documentation-playbook.yml file with contents like this one in it:

site:
  title: Antora Documentation
  url: <documentation-url>
  start_page: documentation::index.adoc

content:
  sources:
    - url: <documentation-1-url>
    - url: <documentation-2-url>

ui: 
  bundle:
    url: <documentation-ui-bundle-url>
    snapshot: true

  output_dir: assets

output:
  clean: true
  dir: ./docs

And to generate the actual final result, we only have to install antora CLI and run a simple command:

$ npm install -g antora
$ antora documentation-playbook.yml

# If you don't want to install globally antora, this is an alternative with npx.
$ npx antora documentation-playbook.yml

This command will generate our bundle inside docs folder and basically that's it.
You only have to deploy it wherever you want to.

Conclusion

After almost 5 repositories we managed to compose up a multi repository documentation: starting from UI, content and actual bundle repository.
This tool is suggested to who wants to build products with multiple versions or a hub of documentations encapsulated in their own repository.
In case you want something lighter and easier, just take a lighter tool like Docusaurus.

Share Support

Documentation Made Easy

Francesco Sardone — Tue, 15 Aug 2023 12:33:00 +0000

Introduction
Requirements
Installation
Running
Configuration
Pages
Conclusion
Share Support

Introduction

Hey there! I'm Francesco known as Airscript on the web.
Today I want to share with you how to use Docusaurus in order to document your next awesome project.
Docusaurus comes as an all-in-one tool, meaning that you can create front pages, blogs and more with it.
I'll be covering only the documentation part with this blog post.

Requirements

Before even starting the next section, be sure to have installed on your machine the only requirement needed: Node.js.
The suggested version goes from 16.14 and above and you can check which one you have just typing node -v inside of your terminal of choice.

Installation

After you got all the requirements, you can easily install docusaurus inside one of your projects by simply running these simple commands:

npx create-docusaurus@latest documentation classic

# If you prefer TypeScript, you can pass an argument for that.
npx create-docusaurus@latest documentation classic --typescript

With the commands above we can create a fully classic docusaurus project, both with or without the usage of TypeScript.
There are more templates such as facebook instead of classic but we're not covering them in this article.

After running that command, you should have a situation like this in the documentation folder:

documentation
├── blog
│   ├── file.md
│   ├── ...
│   └── ...
├── docs
│   ├── file.md
│   ├── ...
│   ├── ...
│   └── ...
├── src
│   ├── css
│   │   └── custom.css
│   └── pages
│       ├── styles.module.css
│       └── index.js
├── static
│   └── img
├── docusaurus.config.js
├── package.json
├── README.md
├── sidebars.js
└── yarn.lock

Running

Now that you have a fully scaffolded project, let's try a simple first run.
It can be done easily following this commands:

cd documentation
npm run start

Configuration

Regarding the configuration part, you may have seen that our documentation right now has some examples in it.
We have to change that in order to reflect our project.
Before all of that, we have to configure how our documentation will be presented.

Inside the project you'll find a docusaurus.config.js file.
This file contains every configuration needed by your documentation site.
Here you can choose if your site needs to have only docs or even a blog!
Or simply change its title or logo.
For more information on what you can do here, just take a look to this documentation page.

Pages

As last, let's see how it's possible to add documentation pages or even edit the existing ones.
Start creating a Markdown file inside the inner docs folder:

touch docs/hello.md

The folder structure will be something like this:

documentation
├── docs
│   └── hello.md
├── src
│   └── pages
├── docusaurus.config.js
├── ...

Then you can start editing that Markdown file, adding some rich content:

---
description: "Hello Page."
---

# Hello
Hey there! I'm a documentation page.

Simple, isn't it?
In this file you can simply use Markdown and everything will be rendered with a rich content inside your documentation site.
I've also provided a description in order to add metadata to this page.
For doing this I've used Front Matter.

Conclusion

And we're at the end of our journey.
We have seen how to install Docusaurus, how to configure it and even how to create our first documentation page.
If you're interested, we can talk about deploying this actual documentation to your preferred site in a later article.
Until then, thank you kindly.

Share Support

Linting Your Awesome Lists

Francesco Sardone — Tue, 08 Aug 2023 08:00:00 +0000

Introduction
Purpose
CLI
Continuous Integration
API
Conclusion
Share Support

Introduction

Hey there! I'm Francesco known as Airscript on the web.
Today I want to share with you how to use awesome-lint, a linter for your Awesome Lists.

Purpose

Awesome Lint was born for helping in standardize and check statically all the Awesome Lists that just try to drop into awesome.

It does a really good job in this for the fact that it is simple to use and usable in so many different ways.
Let's check them all out!

CLI

The first usage that we will see, it is via CLI.
Awesome Lint can be installed via npm or executed using npx:

# Installing through npm
npm install awesome-lint

# Installing temporarily and executing through npx
npx awesome-lint

Then you just need to run it toward one of your repositories, both local or remote:

# If you are into a local repository with a README.md
npx awesome-lint

# If you have installed it globally through npm
awesome-list

# If you don't have the repository locally
awesome-lint https://github.com/airscripts/awesome-steam-deck

At last the command will output something like this:

✖ Linting

  README.md:1:1
  ✖   1:1  Git repository must be at least 30 days old  remark-lint:awesome-git-repo-age
  ✖   1:1  Forbidden license section found              remark-lint:awesome-license
  ✖  24:1  Table of Contents must be the first section  remark-lint:awesome-toc

  3 errors

Continuous Integration

You can also run everything inside your CI pipelines by making sure that your list adheres to the standards after every change.

Just make sure to create the workflow in .github/workflows/main.yml, starting from the root of your project, with the following contents:

name: ci

on:
  pull_request:
    branches: [main]

jobs:
  lint:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2

        with:
          fetch-depth: 0

      - run: npx awesome-lint

API

Awesome Lint also exposes an API that you can use inside of your projects.
Just make sure to first install into your project awesome-lint:

npm install awesome-lint

And after that, you can use it with these two small lines of code:

const awesomeLint = require('awesome-lint');
awesomeLint.report();

The report function just returns the lint output as we have seen previously in CLI section.

Conclusion

So, wrapping up we have seen what Awesome Lint is, how we can use it and how we can integrate it in our automation workflows.
I hope that everything was clear and informative to you.
Thank you kindly for reading this post and I will see you onto the next one!