DEV Community: Eralp

How to Improve Our GitHub? How to Prepare a Profile? How to Write a README?

Eralp — Fri, 29 Nov 2024 07:19:45 +0000

How to Improve Our GitHub? How to Prepare a Profile? How to Write a README?

Hello everyone! In this article, I will cover how to make our GitHub/GitLab profiles, repositories, and README files more effective and professional. Additionally, I’ll explain why these elements are so important. Instead of focusing on questions like What is GitHub? / What is GitLab?, we’ll dive into often-overlooked but globally significant details.

Photo by Roman Synkevych on Unsplash

What is GitHub? What is GitLab?

I won’t go into these topics in detail, but for those who are curious, here are some excellent resources to check out:

Why Are GitHub or GitLab Profiles Important?

The answer is straightforward: Your profile is your digital CV in the software world. Whether you’re applying for a corporate position or working as a freelancer, your CV or portfolio is one of the most critical tools to showcase your skills and experience. In the software industry, the most effective form of this portfolio is your GitHub or GitLab profile.

Moreover, GitHub’s ability to connect you with job opportunities globally makes the content of your profile even more crucial. Thus, not only should your profile be well-organized and professional, but the repositories you direct people to should also be structured, clear, and user-friendly. Your profile and repositories are the most powerful tools to represent you and reflect your skills.

So, How Do You Do This?

If your GitHub profile looks similar to the example below, you probably haven’t created a README.md file or a repository with your username. Let’s create a repository using your GitHub username together! 😊

You can proceed just like creating a normal repository. Enter your GitHub username in the repository name field. GitHub will automatically recognize this as a special profile repository. Then, select Add a README file and create the repository.

Repository Creation Stage

Repository View

Profile View

After creating the repository, your repository will look like the one on the left in the image, and your profile will resemble the one on the right.

Now, it’s time to fill out and enhance your profile README. But how do you do it? Coming up with something from scratch might seem difficult, but there are tools to make this process easier. 😎

How Can I Improve My GitHub Profile?

There are plenty of tools to help with this, so there’s no need to worry. Even if you think your profile doesn’t look great right now, there are websites and ideas to guide you toward improvement. Here are a few tools you can use:

GitHub Profile README Generator: This is one of the simplest and most well-known tools. Created by Rahuldkjain, this excellent open-source project helps you design your profile by selecting a few options and filling out basic information. Initially, it worked with standard templates, but now it even allows you to integrate your Medium or Dev.to posts automatically.
Profilinator: Developed by Rishav, this tool lets you modify styles and layouts via a simple editor. For example, you can divide your page into three sections. It also supports automatic integration of Medium and Dev.to posts.
GPRM: Unlike Rahul’s tool, this one offers easier customization of styles and features, helping you create a unique design language for your profile.

If you prefer not to use a tool and want to design it yourself:

Awesome GitHub Profile

Awesome GitHub Profile: This platform showcases various developer profiles, allowing you to explore different styles and adapt them to your own.

Why Are GitHub Repositories Important?

Repositories play a crucial role in showcasing the technologies, projects, and even small Proof of Concept (PoC) work you’ve done. They demonstrate your knowledge, coding quality, structural skills, and at least your familiarity with a subject. For instance:

In a job interview, saying, “I know Framework A” is very different from saying, “I have several projects using Framework A.” It shows that you’ve gained hands-on experience.
Repositories also highlight your adherence to standards. Most companies, regardless of their level, have some development standards that you’ll need to follow. For example:
Writing meaningful commit messages following the Conventional Commitsstructure.
Using Semantic Versioning for version control.

How Can We Improve the Look of Our GitHub Repositories?

One of the most important elements for making a good impression with a project is the README file. A well-crafted README makes it easier to understand and use your project. The following headings serve as a guide to making your README more effective:

Project Name: This represents the identity of your project and creates the first impression. Choose a short and clear title that defines your project. For example, “Weather Forecast Application.”
Project Purpose: Briefly explain what your project does, the problem it solves, or the need it fulfills. For instance, “This project aims to provide users with real-time weather information. It offers city-based forecasts through a simple and user-friendly interface.”
Project Features: List the main features of your project. This section helps users understand what your project offers:

- City-based weather forecasts
- Real-time updates
- User-friendly interface

Setup Instructions: Provide a step-by-step guide on how to set up and run your project. Create a simple manual suitable for users with varying technical expertise.

1. Clone the repository:
  `git clone https://github.com/username/project-name.git`
2. Install dependencies:
  `npm install`
3. Run the application:
  `npm run dev`

Usage Guide: Explain how to use your project. In this section, you can share example screenshots or commands. For instance: “You can view the weather by selecting a city from the homepage.”
Contributing: Explain how users can contribute to your project. Provide a guide to help users get involved in the development.
- 🛠 Fork the repository.
- Make changes.
- Submit a pull request.
License: Specify the license for your project. This clarifies how users can use and modify your project. For example: “This project is licensed under the MIT License. For more information, please refer to the LICENSE file.”

A typical README file is structured around 7–8 main sections, though the number of sections may vary depending on the level of detail you want to include in your project. Even if you don’t have Markdown knowledge, you can use the following tools to make your repositories more clear and visually appealing:

For those who want simplicity: If you prefer to quickly create a structure with just a few clicks, the CLI-based Readme MD Generator is perfect for you! This tool helps you fill in basic details to generate a README file in no time.
For drag-and-drop users: If you’re looking for a more visual and practical solution, readme.so might be exactly what you need. It allows you to update your information and create a sleek README in minutes.
For those who like to do it all themselves: If you’re more of a “hands-on” person who prefers to write everything from scratch, makeareadme.com is an ideal resource. It not only explains the importance of a READMEbut also provides an editor to assist in the writing process.
For inspiration from other projects: If you’re curious about how other developers approach their READMEs, Awesome README is a great place to start. You can explore examples from various projects, including NASA’s OGMA project, and draw inspiration for your own.

How to Ensure Simplicity and Organization in Your GitHub Repositories?

Having a well-organized and aesthetically pleasing GitHub repository not only enhances its visual appeal but also makes it easier for others to understand and use your project. Here’s a step-by-step guide to achieving simplicity and organization in your repositories:

1. Edit Repository Details

As shown in Images 1–2, you can edit your repository details by navigating to the “Settings” tab at the top of the page and filling in the necessary fields.

Actions:

Description: Write a short sentence explaining the purpose of your project. (e.g., “Weather Forecast Application”).
Website: Add a link to your project’s demo or documentation if available.
Topics: Include relevant categories for your project (e.g., vue3, gpt-4) to improve visibility in search results.

Why Is This Important?
These details help users visiting your project page quickly understand its purpose. Additionally, a well-crafted description enhances your repository’s discoverability on search engines.

Edit Repository Details

Edit Repository Details Screen 2

2. Disable Unnecessary Features

If your project doesn’t use Releases, Packages, or Deployments, you can disable these features (as shown in Images 1–2).

Actions:

Go to the “Edit repository details” menu and check or uncheck the relevant boxes to disable unnecessary features.

Why Is This Important?
Unused or empty sections can make your repository look cluttered. Keeping only actively used features visible adds simplicity and professionalism to your project.

3. Customize Wiki, Issues, and Projects Settings

As shown in Images 3 and 4, you can enable or disable Wiki, Issues, and Projects based on your project’s requirements.

Actions:

Wiki: Keep this open if you need a space for project documentation. Restrict editing to collaborators by enabling the “Restrict editing to collaborators only” option.
Issues: Enable this feature to allow contributions and bug tracking. You can also add an Issue Template for structured feedback.
Projects: Use this section to manage project-specific tasks and timelines. Enable it if task management within the repository is necessary.

Why Is This Important?
Managing these features according to your project’s needs keeps the repository organized and focused. Disabling unused features prevents unnecessary clutter and enhances the repository’s usability.

Screen-3

Screen-4

4. Fill in Required Fields

Empty or missing details in your repository’s About section (e.g., Description, Topics) can make the repository appear incomplete and unappealing.

Actions:

Fill in all required fields.
Use a description and tags that align with your project to achieve a professional appearance.

Why Is This Important?
Incomplete information makes it harder for users to understand your project and can make the repository seem amateurish.

5. Language Usage and Visuals

The Languages section in your repository reflects the programming languages used, giving users insights into your code structure. Additionally, enhancing your README file with effective visuals can make your project more appealing.

Actions:

Add screenshots or diagrams in the README file to explain the project’s structure and usage.
Include code snippets with usage instructions to provide clear guidance.

Why Is This Important?
Both textual and visual explanations help users quickly grasp the project and encourage contributions.

6. Conclusion: A More Unique and Streamlined Repository

By following these steps, you can simplify and refine your GitHub repository, making it more professional and user-friendly. A well-organized and up-to-date project page is crucial for users looking to evaluate the quality and relevance of your project. Simplicity and functionality not only attract users but also motivate potential contributors.

A polished repository is the most effective way to showcase your project and engage the community!

Remember, a well-designed repository is the most effective way to present your project and capture the community’s interest! — ChatGPT

In this article, I focused on the importance of GitHub/GitLab profiles and README files, sharing key points and tools to help you improve them.

If you have any questions or suggestions, feel free to reach out to me via my LinkedIn profile. You can also find me on Bento.me/eralpozcanor eralpozcan.dev. 🤖

Don’t forget to follow me on GitHub and drop your GitHub profiles in the comments 🎁

See you in the next article! 📩

Github’ımız Nasıl Daha İyi Hale Getirilir? Profil Nasıl Hazırlanır? README Nasıl Yazılır?

Eralp — Fri, 29 Nov 2024 00:21:03 +0000

Github’ımız Nasıl Daha İyi Hale Getirilir? Profil Nasıl Hazırlanır? README Nasıl Yazılır?

Herkese merhaba! Bu yazıda, GitHub/GitLab profillerimizi, repolarımızı ve README dosyalarımızı nasıl daha etkili ve profesyonel hale getirebileceğimizi ele alacağım. Bunun yanı sıra, neden bu kadar önemli olduklarına dair bilgiler paylaşacağım. GitHub Nedir? / GitLab Nedir? gibi temel soruların ötesine geçerek, birçok kişinin gözden kaçırdığı ancak global ölçekte oldukça önemsenen noktalara değineceğim.

Github Nedir? Gitlab Nedir?

Bu konulara detaylıca değinmeyeceğim, ancak merak edenler için birkaç kaynağı aşağıya bırakıyorum:

GitHub veya GitLab Profilimiz Neden Önemli?

Bu sorunun cevabı oldukça basit: Profiliniz, yazılım dünyasındaki dijital CV’nizdir. Günümüzde, ister kurumsal bir işe başvuruyor olun ister freelance çalışıyor olun, sunduğunuz CV (özgeçmiş) veya portföy, yeteneklerinizi ve deneyimlerinizi sergilemenin en önemli araçlarından biri. Yazılım dünyasında ise, bu portföyün en etkili hali GitHub veya GitLab profilinizdir.

Dahası, GitHub üzerinden iş bulma imkanları, profillerinizin içeriklerini çok daha önemli hale getiriyor. Bu nedenle, sadece profilinizin değil, yönlendirdiğiniz repoların da düzenli, anlaşılır ve profesyonel bir yapıda olması gerekiyor. Profiliniz ve repolarınız, sizi tanıtan ve yeteneklerinizi yansıtan en güçlü araçlardır.

Peki bunu nasıl yapacağım?

Öncelikle, GitHub profiliniz aşağıdakine benzer bir yapıda ise daha önce profiliniz için bir README.md dosyası, yani kendi kullanıcı adınızla bir repository oluşturulmamış demektir. Şimdi, birlikte kendi kullanıcı adımızla bir repository oluşturalım. :)

Varsayılan Github Profile Görünümü

Normal bir repository oluşturur gibi işlem yapıyoruz. Repository name alanına GitHub kullanıcı adımızı yazıyoruz. GitHub, bu adı algılayarak bize özel bir profil repository’si oluşturacağımızı otomatik olarak tanıyor. Ardından, alt seçeneklerden Add a README file seçeneğini işaretleyerek repository’yi oluşturuyoruz.

Repository Oluşturma Aşaması

Readme Oluşturulmuş Repository Görünümü

Readme Oluşturulmuş Profil Görünümü

Repository’yi oluşturduktan sonra, repository’niz görseldeki gibi (Sol) bir yapıya sahip olacaktır. Profiliniz ise görseldeki gibi (Sağ) bir görünüm kazanacaktır.

Artık profil README’nizi doldurma ve güzelleştirme zamanı geldi. Peki, bunu nasıl yapacağız? Hemen bir şeyler yaratmak zor olabilir, ancak bunu kolaylaştıracak araçlar mevcut. 😎

Github Profilimi Nasıl İyi Hale Getiririm? Nasıl doldurabilirim?

Aslında bunun için bir çok araç olduğundan yazının yukarısında bahsetmiştim. Bu yüzden endişe edeceğimiz bir durum yok. Hatta kötü olduğunu düşünüyorsanız bile iyi yapacak fikirler için bile websiteler mevcut. Bu araçlara gelecek olursak ;

Github Profile Readme Generator: Belki de en basit, kullanımı kolay ve en çok bilinen araçlardan biri olduğunu söyleyebilirim. Rahuldkjain tarafından geliştirilen bu güzel açık kaynak proje, seçimlerinizi yaparak ve birkaç temel bilgiyi doldurarak profilinizi oluşturmanızı sağlıyor. Proje, ilk başlarda standart şablonlar üzerinde çalışıyordu, ancak günümüzde Medium veya Dev.to yazılarınızı bile otomatik olarak profilinize eklemenizi sağlayan bir eklenti ile birlikte geliyor.
Profilinator: Rishav’ın geliştirdiği bu araç ise basit bir editor aracılıyla yapmış olduğunu stili ve tasarımları değiştirebiliyorsunuz. Örneğin sayfayı 3’e bölmek gibi. Yine burada Medium veya Dev.to yazılarınızı otomatik olarak ekleyebilirsiniz.
GPRM: Rahul’un yaptığından farklı olarak bu aracımızda bazı stillemeler ve özellikleri daha kolay olarak seçerek tercih edebiliyor farklı bir tasarım dili ortaya çıkartabiliyorsunuz.

Eğer ki araç kullanmak istemiyorum. Stilleri merak ediyorum kendim de ona göre yapacağım derseniz;

Awesome Github Profile

Awesome Github Profile: Burada ise farklı yazılım geliştiricilerin kendi sayfalarını paylaştığı ve stil tarz anlamında farkılıkları görebileceğiniz ve esinlenip kendinize uyarlayabileceğiniz mükemmel bir site.

Github Repolarımız Neden Önemli?

Repolarımız bizim yapmış olduğumuz öğrendiğimiz her teknolojinin, her projenin veya yapmış olduğumuz küçük PoC(Proof of Concept)’ler barındırması dolayısıyla önem arz ediyor. Çünkü burada yapmış olduğumuz projeler bir konu hakkında bilgimizi, kod yazma kalitemizi, yapısal bilgilerimizi veya en azından o konu ile alakalı aşinalığımızı ispatlar nitelikte olmuş oluyor. Örneğin; Bir mülakatta “A Framework’ünü kullanmayı biliyorum” demeniz ile “A Framework’ü ile bir kaç temel projeye sahibim” demeniz arasında dağlar kadar fark var. En basit haliyle size devamında gelecek sorular genellikle hakim olduğunuz yerlerden olacaktır. Çünkü klasik tabir ile elinizi hamura buladınız.

Bu repoların bir diğer önemi, projelerinizin hangi standartlara uygun olarak geliştirildiğini göstermesidir. Hangi şirkete giderseniz gidin, belirli standartlara uyum sağlamanız beklenecektir. Örneğin, git commit mesajlarınızın anlamlı ve belli bir yapı çerçevesinde olması beklenir. Çoğu açık kaynak projede Conventional Commits yapısı tercih edilir ve siz de commit mesajlarınızı bu standartlara uygun hale getirebilirsiniz. Ayrıca, versiyonlama için Semantic Versioning gibi bir yapıyı öğrenmek ve uygulamak da oldukça faydalı olacaktır. Bu tür yaklaşımlar, projenize verdiğiniz önemi ve profesyonelliğinizi yansıtır.

Github Repolarımızın Görünümü Nasıl İyi Yapabiliriz?

Bir projenin iyi bir izlenim bırakması için en önemli unsurlardan biri README dosyasıdır. İyi bir README dosyası, projeyi anlamayı ve kullanmayı kolaylaştırır. Aşağıdaki başlıklar, README’nizi daha etkili hale getirmek için bir rehber niteliğindedir:

Proje Adı: Projenin kimliğidir ve ilk izlenimi oluşturur. Projenizi tanımlayan kısa ve anlaşılır bir başlık seçin. Örneğin, “Hava Durumu Tahmin Uygulaması” gibi.
Projenin Amacı: Projenizin ne işe yaradığını, hangi sorunu çözdüğünü veya hangi ihtiyacı karşıladığını kısa ve öz bir şekilde açıklayın. “Bu proje, kullanıcılara gerçek zamanlı hava durumu bilgileri sağlamayı amaçlamaktadır. Basit ve kullanıcı dostu bir arayüzle şehir bazlı tahminlere ulaşabilirsiniz.”
Projenin Özellikleri: Projenizin temel özelliklerini listeleyin. Kullanıcılar bu bölümde projenizin neler sunduğunu öğrenebilir.Şehir bazlı hava durumu tahminiGerçek zamanlı güncellemelerKullanıcı dostu arayüz
Kurulum Talimatları: Projenizin nasıl kurulacağını ve çalıştırılacağını adım adım açıklayın. Teknik bilgi seviyesi farklı olan kullanıcılar için basit bir rehber oluşturun.

1. Depoyu klonlayın:
  `git clone <https://github.com/kullaniciadi/proje-adi.git>`
2. Gerekli bağımlılıkları yükleyin:
  `npm install`
3. Uygulamayı başlatın:
  `npm run dev`

Kullanım Kılavuzu: Projenizin nasıl kullanılacağını açıklayın. Bu bölümde örnek ekran görüntüleri veya komutlar paylaşabilirsiniz. “Ana sayfadan bir şehir seçerek hava durumunu görüntüleyebilirsiniz.”
Katkıda Bulunma : Projenize nasıl katkıda bulunulabileceğini açıklayın. Kullanıcıların projeye dahil olması için rehberlik sunun.

- 🛠 Bu projeyi fork edin
- Değişikliklerinizi yapın
- Bir pull request gönderin

Lisans: Projenizin lisansını belirleyin. Bu, kullanıcıların projenizi nasıl kullanabileceğini ve değiştirebileceğini açıklar. Örneğin: “”Bu proje MIT Lisansı ile lisanslanmıştır. Daha fazla bilgi için LICENSE dosyasına bakabilirsiniz.”

Genel olarak bir README dosyası 7–8 ana başlık altında yapılandırılır, ancak bu başlık sayısı, projenizde vermek istediğiniz detaylara göre değişiklik gösterebilir. Markdown bilginiz olmasa bile, aşağıda paylaştığım birkaç kullanışlı araç sayesinde repolarınızı daha anlaşılır ve estetik hale getirebilirsiniz:

Detaylarla uğraşmak istemeyenler için: Eğer sadece birkaç tuşlama ile hazır bir yapı oluşturmak istiyorsanız, CLI tabanlı bir araç olan Readme MD Generator tam size göre! Bu araç, temel bilgileri doldurarak hızlıca bir README oluşturmanızı sağlar.
Sürükle-bırak yöntemiyle çalışanlar için: Eğer daha görsel ve pratik bir çözüm arıyorsanız, readme.so, ihtiyacınızı karşılayabilir. Sadece bilgilerinizi güncelleyerek kısa sürede şık bir README oluşturabilirsiniz.
Her şeyi kendisi yapmayı sevenler için: Eğer “Ben old school’um, her şeyi kendim yaparım, README’mi de kendim yazarım” diyorsanız, makeareadme.com sizin için ideal bir kaynak. Burada README yazmanın neden önemli olduğunu öğrenebilir ve yazım sürecini destekleyecek bir editör kullanabilirsiniz.
Farklı projelerden ilham almak isteyenler için: Eğer “Diğer projeler bunu nasıl yapıyor?” diye merak ediyorsanız, Awesome README tam da bu ihtiyaca yönelik. NASA’nın OGMA projesi gibi birçok farklı projeden örnek README dosyalarını inceleyerek ilham alabilirsiniz.

GitHub Repository’lerinizde Sadelik ve Düzen Nasıl Sağlanır?

GitHub projelerinizin hem estetik hem de işlevsel açıdan daha düzenli görünmesi, diğer kullanıcıların projeyi anlamasını ve kullanmasını kolaylaştırır. Aşağıda bu süreci adım adım açıklıyorum.

1. Repository Detaylarını Düzenleyin

Görsel 1-2'de olduğu gibi, repository bilgilerinizi düzenlemek için üst kısımdaki “Settings” sekmesine giderek detayları doldurabilirsiniz.

Eylemler:

Description (Açıklama): Kısa bir cümle ile projenizin amacını yazın. (Örn: “Hava Durumu Uygulaması”)
Website: Eğer projenize ait bir demo veya dökümantasyon linki varsa buraya ekleyin.
Topics: Projenizin kategorilerini (örn: vue3, gpt-4) ekleyerek arama sonuçlarında daha görünür hale getirin.

Neden Önemli?Bu bilgiler, proje sayfasını ziyaret eden kullanıcıların proje hakkında hızlıca bilgi edinmesini sağlar. Ayrıca doğru doldurulmuş bir açıklama, arama motorlarında projenizin daha kolay bulunmasına katkı sunar.

2. Gereksiz Alanları Kapatın

Eğer projenizde bir Release, Package ya da Deployment kullanımı yoksa, bunları devre dışı bırakabilirsiniz (Görsel 1–2).

Eylemler:

“Edit repository details” menüsünden ilgili kutucukları işaretleyerek ya da kaldırarak gereksiz özellikleri kapatın.

Neden Önemli?Boş veya kullanılmayan alanlar, repository’nin gereksiz kalabalık görünmesine neden olabilir. Sadece aktif olarak kullanılan özellikleri açık bırakmak, projenize sadelik ve profesyonellik katar.

3. Özelleştirme için Wiki, Issues ve Projects Ayarları

Görsel 3 ve Görsel 4'da gösterildiği gibi, Wiki, Issues ve Projects özelliklerini projenizin ihtiyaçlarına göre açıp kapatabilirsiniz.

Eylemler:

Wiki: Eğer proje için dökümantasyon yazmak istiyorsanız açık bırakın. Sadece proje ekibinin düzenlemesine izin vermek için “Restrict editing to collaborators only” seçeneğini işaretleyin.
Issues: Eğer projeye katkı sağlanmasını istiyorsanız bu alanı açık bırakın. Ayrıca, düzenli takip için bir Issue Template ekleyebilirsiniz.
Projects: Projeye özel görevlerinizi ve takvimlerinizi burada yönetmek istiyorsanız açık bırakabilirsiniz.

Neden Önemli?Bu alanların ihtiyaçlara göre yönetilmesi, repository’nin daha düzenli ve hedef odaklı olmasını sağlar. Kullanılmayan özellikler, gereksiz karmaşaya neden olur.

4. Doldurulması Gereken Alanları Atlamayın

Repository’nizin About bölümündeki boşluklar veya eksik bilgiler (örneğin Description, Topics) repository’nin eksik ve ilgisiz görünmesine yol açabilir.

Eylemler:

Tüm gerekli alanları doldurun.
Projenizle uyumlu bir açıklama ve etiketler kullanarak profesyonel bir görünüm elde edin.

Neden Önemli?Eksik bilgiler, kullanıcıların proje hakkında bilgi edinmesini zorlaştırır ve repository’nin amatör görünmesine neden olabilir.

5. Dil Kullanımı ve Görsellik

Repository’nizde kullanılan programlama dillerini temsil eden Languages kısmı, projeyi inceleyen kişilere kod yapınız hakkında bilgi verir. Ayrıca README’nizi etkili görsellerle destekleyerek projenizi daha çekici hale getirin.

Eylemler:

README dosyasına proje yapısını ve kullanımını anlatan ekran görüntüleri ekleyin.
Kod snippet’leriyle örnek kullanım talimatlarını gösterin.

Neden Önemli?Hem yazılı hem görsel açıklamalar, kullanıcıların projeyi daha hızlı anlamasına yardımcı olur ve katkıda bulunmalarını teşvik eder.

6. Sonuç: Daha Özgün ve Sade Bir Repository

Bu adımları uygulayarak, GitHub repository’nizi gereksiz detaylardan arındırabilir, daha profesyonel ve kullanıcı dostu bir görünüm kazandırabilirsiniz. Düzenli ve güncel bir proje sayfası, projenizin genel görünümünü ve kalitesini hızlıca değerlendirmek isteyen kullanıcılar için büyük önem taşır. Sadelik ve işlevsellik, hem kullanıcıların ilgisini çeker hem de katkı sağlamak isteyenler için motive edici bir etki yaratır.

Unutmayın, iyi tasarlanmış bir repository, projenizi anlatmanın ve topluluğun ilgisini çekmenin en etkili yoludur! — ChatGPT

Bu yazıda, GitHub/GitLab profillerinin ve README dosyalarının önemine odaklanarak, bunları nasıl daha iyi hale getirebileceğinizle ilgili önemli noktaları ve araçları paylaştım.

Sorularınız veya önerileriniz varsa, LinkedIn hesabımdan bana ulaşabilirsiniz. Diğer hesaplarıma ise Bento.me/eralpozcan veya eralpozcan.dev üzerinden erişebilirsiniz. 🤖

Beni Githubdan takip etmeyi ve yorumlara Github adreslerinizi bırakmayı unutmayın 🎁

Bir sonraki yazıda görüşmek üzere! 📩

How to Use Object Recognition with TensorFlow.js and Vue 3?

Eralp — Fri, 02 Feb 2024 00:43:41 +0000

In recent years, artificial intelligence and its products have become increasingly active and are starting to take their place in our lives, with their numbers steadily rising. We all have the question in mind of how we can use this in our daily lives. In this article, we will create a simple application together using TensorFlow.js, where we will use ImageNet classes and the MobileNet-v2 model to recognize and add an object/item to the cart. This way, we will implement a scenario similar to the basic working principle of Amazon Go. Let's get started 🚀

What is TensorFlow? What is TensorFlow.js?

TensorFlow is an open-source machine learning and deep learning library developed by Google. Widely supported by a large community, TensorFlow is a powerful tool used for artificial intelligence applications and large-scale data processing projects. It is extensively used in both research and industrial projects, featuring a flexible and modular structure with the capability to run on different devices such as computers, mobile devices, and IoT devices.

TensorFlow.js is the JavaScript version of TensorFlow, enabling the training and execution of machine learning models in the browser. This makes it a suitable tool for web applications and browser-based artificial intelligence projects.

Installations

Firstly, let's create our Vue 3 project. You can use either Vue CLI or Vite for this. I will prefer Vite for the installation here, but you can choose Vue CLI for a simplified setup with other tools.

npm create vite@latest tf-js-with-vue -- --template vue
# yarn
yarn create vite my-vue-app --template vue
# If you choice Vue CLI Commands
npm create vue@latest

📌 Optional Installation

If you want to use a UI or CSS library, I recommend installing it at this stage. In this example project, I used TailwindCSS and DaisyUI. If you want to follow the same structure:

After completing the installations, go to the project directory and run npm install and npm run dev to run our empty project. If you don't encounter any issues or errors, you can proceed to add TensorFlow.js to your project by visiting TensorFlow.js Installation.

npm install @tensorflow/tfjs
# yarn
yarn add @tensorflow/tfjs

📌 How to Use TensorFlow.js?

To use TensorFlow.js, create a file named tensorflowImageClassifier.js under a utils folder. Inside this file, add the following code:

import * as tf from '@tensorflow/tfjs';
let model
let labels
let labelsArray

Here, we imported TensorFlow.js with the alias "tf". We then defined the variables model, labels, and labelsArray, which will contain the organized labels.

📌 Loading the Model and Labels

After these definitions, create a function named loadModel. In this function, we will load our model and labels into the project.

async function loadModel() {
  model = await tf.loadGraphModel("https://www.kaggle.com/models/google/mobilenet-v2/frameworks/TfJs/variations/035-128-classification/versions/3", { fromTFHub: true })
  labels = await fetch("https://storage.googleapis.com/download.tensorflow.org/data/ImageNetLabels.txt")
  .then((res) => res.text())
  labelsArray = labels.split('\n').map(label => label.trim()).filter(label => label !== '');
}

Firstly, we load our model using tf.loadGraphModel from Kaggle-MobileNet-v2 by Google.
At this stage, we fetch the labels of the ImageNet data and convert it into a text format.
Finally, we transform this text data into an array and assign it to the variable labelsArray.

Function Explanations:

tf.loadGraphModel: TensorFlow.js model loading function. It loads the model from the specified URL.
fetch: Fetches data from the specified URL.
labels.split('\n'): Splits the labels by new lines and converts them into an array.
map(label => label.trim()): Removes leading and trailing spaces for each label in the array.
filter(label => label !== ''): Filters out empty labels.

📌 Image Classification Function

Now, let's create the following function to classify an image using the loaded model:

async function classifyImage(image) {
  // 1. Convert Input Image to Tensor and Preprocess
  const imgTensor = tf.browser.fromPixels(image)  // Convert the image to a Tensor
    .resizeNearestNeighbor([128, 128])  // Resize the image to 128x128 dimensions
    .toFloat()  // Convert Tensor values to floating-point numbers
    .div(tf.scalar(255))  // Normalization: Scale pixel values from [0, 255] to [0, 1]
    .expandDims();  // Expand the Tensor dimension

  // 2. Classify the Image with the Model
  const predictions = await model.predict(imgTensor);  // Classify the image using the model

  // 3. Determine and Sort the Top Probability Classes
  const topPredictions = Array.from(predictions.dataSync())  // Convert from Tensor to JavaScript array
    .map((probability, index) => ({ probability, label: labelsArray[index]}))  // Match probability and label for each class
    .sort((a, b) => b.probability - a.probability)  // Sort by probability
    .slice(0, 3);  // Select the top three classes with the highest probabilities

  // 4. Return the Results
  return topPredictions;  // Return an array containing the top probable classes
}

This function takes an image, converts it to the TensorFlow.js tensor format, and applies necessary preprocessing steps. Then, it classifies the image using the model and returns an array containing the top three classes with the highest probabilities.

tf.browser.fromPixels(image): Converts the input image to the TensorFlow.js tensor format.
Applies some preprocessing on the tensor. Resizes the image to 128x128 dimensions, normalizes pixel values, and expands the tensor dimension.
model.predict(imgTensor): Uses the TensorFlow.js model to classify the preprocessed image and obtains a tensor containing probabilistic results.
Converts the obtained results to a JavaScript array, matches the probability and label for each class, sorts by probability, and selects the top three classes with the highest probabilities.
Finally, the function returns an array containing the labels and probabilities of the top three classes. This array represents the classification results.

📌 Creating Mockup Data

Since we have a shopping cart scenario in the project, we need to retrieve the classified items from the database. However, to keep dependencies minimal, we will read our mockup data from a JSON file and return the necessary information.

First, create a folder named services under the src directory.
Then, create a file named data.json inside the services folder and open it. I added four pieces of data as an example based on ImageNet labels, but you can increase this as needed.

[
  {
    "id": "1a23bc45-678d-90ef-ghij-klmnopqrstuv",
    "name": "background",
    "price": 10.99
  },
  {
    "id": "2b34cd56-789e-01fg-hijk-lmnopqrstuvi",
    "name": "tench",
    "price": 15.99
  },
  {
    "id": "3c45de67-890f-12gh-ijkl-mnopqrstuvij",
    "name": "French loaf ",
    "price": 8.99
  },
  {
    "id": "3c45de67-890f-12gh-ijkl-mn423rstuvij",
    "name": "bread",
    "price": 12.99
  }
]

After completing this stage, we will create a simple code structure to read our data and return product information based on the result of the classification.

Create a file named productService.js. Import the mockup data into this file using import mockupData from './data.json'.
Since we will perform a simple search on our data, create a function named searchByName.

import mockupData from './data.json';
function searchByName(query) {
  const lowerCaseQuery = query.toLowerCase();
  return mockupData.filter(item => item.name.toLowerCase().includes(lowerCaseQuery));
}
export { searchByName };

📌 Vue.js Image Recognition with TensorFlow

In the previous stages of the tutorial, we prepared TensorFlow.js and the necessary requirements. Now, let's move on to the easier part, the Front End. We will create three main components. You can also create them as a single component if you prefer.

Components

ImageUpload.vue
ResultDisplay.vue
SimpleBasket.vue

View

HomeView.vue

Firstly, we create a component named ImageUpload.vue.

We design it with the essential functionalities. Feel free to add extra details or functions. You can also break it down into sub-components for more efficient code 😛

Design

<template>
  <div class="flex flex-col items-center">
    <div class="indicator">
      <span v-if="loadingImage" class="indicator-item indicator-center indicator-middle badge badge-primary">Uploading Image...</span>
      <img :src="previewImage" alt="Input Image" class="w-96 h-96 my-2 rounded" />
    </div>
    <input type="file" accept="image/*" class="file-input w-full max-w-xs mb-2" alt="Image Input" @change="handleImageUpload" />
    <button class="btn btn-primary w-32" @click="processImage" :disabled="!isImageSelected">Classify or Recognize</button>
  </div>
</template>

Here, we will take an image from the user and trigger its classification/recognition through a button.

Functions

In this stage, instead of explaining the code step by step, I'll share the entire code with you and explain its functions.

import { ref, computed } from 'vue';
// Import the classifyImage and loadModel functions from the tensorflowImageClassifier module
import { classifyImage, loadModel } from '@/utils/tensorflowImageClassifier';
// Create a reactive array to hold image classification results
const classificationResults = ref([]);
// Create a reactive variable to hold the preview image URL, initially set with a placeholder URL
const previewImage = ref("https://placehold.co/600x600");
// Create a reactive boolean variable to track the loading status of the image
const loadingImage = ref(false);
// Define custom events to be used within the component using the defineEmits function of Vue.js
const emit = defineEmits(['getResult', 'getProducts']);
// Create a computed property to check whether the user has selected an image
const isImageSelected = computed(() => previewImage.value !== "https://placehold.co/600x600");
// Event handler function triggered when the user selects a file
const handleImageUpload = (event) => {
  const file = event.target.files[0]; // Get the selected file
  const image = new Image(); // Create a new HTML image element
  const reader = new FileReader(); // Create a FileReader for file reading operations

  // When the file reading process starts
  reader.onloadstart = () => {
    previewImage.value = previewImage; // Set the preview image (this line seems to have no correct function)
    loadingImage.value = true; // Set the image loading status to true
  };

  // When the file reading process is completed
  reader.onloadend = () => {
    loadingImage.value = false; // Set the image loading status to false
    image.src = reader.result; // Set the source of the image element with the read data
    previewImage.value = reader.result; // Set the preview image with the read data
  };

  // Start the reading process by converting the file to base64 format
  reader.readAsDataURL(file);
};

// Event handler function that initiates image classification
const processImage = async () => {
  if (previewImage.value) { // If a preview image is available
    const image = new Image(); // Create a new HTML image element
    image.src = previewImage.value; // Set the source of the image element with the preview image URL
    await loadModel(); // Load the TensorFlow model
    classificationResults.value = await classifyImage(image); // Classify the image and assign the results to classificationResults
    emit('getResult', classificationResults.value); // Trigger the 'getResult' event and pass the results to upper-level components
    emit('getProducts', classificationResults.value); // Trigger the 'getProducts' event and pass the results to upper-level components
  }
};

classificationResults: An array holding the results of image classification.
previewImage: A string holding the URL of the user-uploaded or selected image for preview. Initially starts with a placeholder URL.
loadingImage: A boolean variable indicating the loading status of the image. Initially set to false and updated within the function.
isImageSelected: A computed property checking whether the user has selected an image, determining the enable/disable status of the "Classify" button. It checks if the preview URL is different from the placeholder.
handleImageUpload: This function is triggered when the user selects a file. It reads the content of the selected file and converts it into an image for preview. It also shows a loading element while the image is being loaded.
processImage: This function initiates the image classification process. If a preview image is available, it loads a pre-trained model and classifies the image. The results are stored in classificationResults, and events (getResult and getProducts) are emitted to pass the results to upper-level components.

ResultDisplay.vue

<script setup>
defineProps({
  labels: Array
});
</script>

<template>
  <div class="bg-white-800 dark:bg-gray-800 p-4 my-2 rounded shadow-md">
    <h2 class="text-2xl text-slate-600 dark:text-slate-400 font-bold mb-4">Classification Result</h2>
    <ul>
      <li v-for="(result, index) in labels" :key="index" class="mb-2 p-2 border rounded">
        <span class="font-semibold text-slate-600 dark:text-slate-400">{{ result.label }}</span> - {{ (result.probability).toFixed(2) }}
      </li>
    </ul>
  </div>
</template>

In this component, we will display the top 3 probabilities on the screen. The reason for having 3 probabilities is that in our classifyImage function, we use slice(0,3) to take the top 3 probabilities. For example, if it were slice(0,5), we would see the top 5 probabilities.

SimpleBasket.vue

<script setup>
defineProps({
  products: Array
});
</script>

<template>
  <div class="mx-auto bg-white-800 dark:bg-gray-800 rounded p-4 mt-2 shadow-md">
    <h2 class="text-xl font-semibold mb-4">Product Basket</h2>
    <div class="flex justify-between items-center border-b pb-4 mb-4" v-for="product in products" :key="product.id">
      <div>
        <h3 class="text-lg text-balance font-medium">1x {{ product.name }}</h3>
      </div>
      <div class="flex items-center">
        <span class="text-slate-600 dark:text-slate-400 font-semibold">Price: {{ product.price }}</span>
      </div>
    </div>
  </div>
</template>

In this component, we handle the scenario of finding the product and adding it to the basket after our basic scenario. Here, in our upper layer, which is the HomeView.vue layer, we find the product, send its information to this component, and display it.

HomeView.vue

<script setup>
import { ref } from 'vue'
import ImageUpload from '@/components/ImageUpload.vue'
import ResultDisplay from '@/components/ResultDisplay.vue'
import SimpleBasket from '@/components/SimpleBasket.vue'

const classificationResults = ref([])
const products = ref([])

const getResult = (result) => {
  classificationResults.value = result;
}
const getProducts = (result) => {
  products.value = result
};
</script>

<template>
  <ImageUpload @getResult="getResult" @getProducts="getProducts" />
  <ResultDisplay v-if="classificationResults.length > 0" :labels="classificationResults" />
  <SimpleBasket v-if="classificationResults.length > 0" :products="products" />
</template>

After calling our components in HomeView.vue, we obtain the appearance in our visualization. If there are any differences or missing parts in your view, you can check TF.js-with-Vue3 for the repository. Alternatively, you can download it directly to your computer.

Now that we have completed all these stages, let's move on to testing our project. As an example, I chose one of the images that appear when searching for "French Loaf" on Google because it is available within the ImageNet labels. We have also defined its classification in our Mockup Data.

After selecting and uploading our image, we press the "Classify-Recognize" button. We then display the top 3 predictions with high probabilities and automatically add the item to our basket.

As we can see, we implemented a simple Object Recognition and Add to Cart scenario using TensorFlow.js in the project. Through this, we explored how we can easily integrate artificial intelligence and tools into our projects or daily scenarios.

In this article, I tried to explain the usage and installation of TensorFlow.js with examples of how it can be beneficial in a simple scenario.

After reading my post, feel free to reach out to me on LinkedIn if you have any questions or suggestions.For my other accounts, you can visit Bento.me/eralpozcan 🤖

See you in the next article! 📩

How to Use Sentry with Vue 3?

Eralp — Mon, 17 Jul 2023 17:54:02 +0000

Don’t we often encounter errors and find it difficult to identify them? One of the error and performance monitoring tools is Sentry. In this article, I will explain how to set up Sentry and make improvements with performance monitoring. Are you ready? Let’s get started! 🚀

What is Sentry?

Sentry can be described as an error monitoring and reporting platform for many of our applications if we need to provide a general definition. We can even add that it is a performance reporting platform.

Sentry enables developers to monitor application errors in real time, receive and analyze error reports, and quickly diagnose issues.

The key features of Sentry include:

Error Tracking: Sentry tracks and captures errors in applications. It can detect various types of errors such as exceptions, error messages, errors in the user interface, and more.
Real-time Monitoring: Sentry monitors application errors in real-time and sends notifications promptly. This allows developers to quickly notice mistakes and take action.
Error Reporting: Sentry reports errors in detail. Error reports provide crucial information about when, where, and under what conditions the error occurred. This helps developers diagnose and fix errors.
Integrations: Sentry supports many popular programming languages and various platforms. This allows it to integrate with different types of applications and systems.
Performance Monitoring: Sentry can monitor the performance of applications and detect performance issues. With performance monitoring features, developers can optimize the performance of their applications and enhance the user experience. We’ll even provide an example in this regard 😉

Additionally, in addition to the basic explanation provided here, I recommend reading Onur Dayıbaş’s Medium article titled “Some Concepts in Sentry”

Installation

Firstly, I will support the steps we will take here with visuals. Sentry itself will also provide us with sufficient assistance in this regard.

📌 Go to Sentry’s website and create an account if you don’t have one, or log in if you already have an account.

📌 If you’re logging in for the first time, you’ll be prompted to create an organization. One of the main reasons for this is to enable collaboration with your team members. In this example, I’ll skip this step by creating an organization named “Example”.

📌 We are presented with a screen where we can choose the platform we want to set up. Here, we select Vue.

📌 Here, we select the alert frequency. We can adjust this setting later, but for now, we select the option “Alert me on every new issue.” Then, we proceed to the next step, where we create our project and choose our team. If you don’t have a team, by default, it will use the name of your organization as the team. If you want to create a different team, you can click on the “+” sign to create one. Finally, we click on “Create Project.”

📌 Here, Sentry provides us with instructions. It automatically adjusts settings based on three main scenarios. Some important points to understand are as follows:

Error Monitoring: This is our error monitoring setting. It is selected by default, and we cannot disable it because that’s our primary goal 😉
Performance Monitoring: Here, we measure the performance of our page load. If we don’t want this option, we can remove it.
Session Replay: This is actually one of the features we love. It provides a small video snippet showing how errors occurred. However, it is not recommended to collect these data at high rates. It’s sufficient to enable it only for errors.

Let’s move on to the installation process. As shown in the screenshot above, we install the Sentry package in our project using either “npm” or “yarn” depending on our preference. Then, we directly copy the Vue3 sample code and paste it into our “main.js” file. Of course, you may have a different “main.js” file in your project. The important point here is to include the portion starting with Sentry.init({]) (Don’t forget to import it). The key settings and their meanings in this configuration are as follows:

App: It is used to specify the application object, which is the application we created with createApp or the application we want to monitor.
dns: The address of the Sentry server where error reports will be sent. I recommend keeping this address in a secure manner, such as using a .env file. Exposing this address can lead to potential security issues.
integrations: It is used to configure Sentry integrations. In this example, Sentry.BrowserTracing and **Sentry.Replay **integrations are used.
tracesSampleRate: Performance monitoring sample rate. It is expressed as a percentage, and in this example, it is set to 100%. It is recommended to lower this rate in real production environments.
replaysSessionSampleRate: Session replay sample rate. It is expressed as a percentage, and in this example, it is set to 10%. During development, it can be set 100% for better analysis, while in production, a lower sampling rate can be used.
replaysOnErrorSampleRate: Sample rate for sessions with errors. If you are not already sampling sessions, you can set the sampling rate for sessions with errors to 100%.

For more advanced configuration options that are not shown in the screenshot, you can refer to the Sentry Basic Options in the documentation to make detailed adjustments. Essentially, we have completed the basic installation process here. Now, let’s see how we can capture our first error.

Issues

After completing the installations,** Sentry** automatically redirects us to a page like the one below and expects us to send our errors. In fact, we will see or track all the errors here.

How can we send this error or different data to Sentry? 🤔

👩‍💻We are creating a simple button and function.

<button @click="sendSentryData">Click me</button>

function sendSentryData() {
   Sentry.captureMessage('Button clicked');
}

If you haven’t imported and initialized Sentry when creating this function, you will receive the error shown in the image below.

We encountered our first error! So how did this happen?

Because we encountered a reference error at its core, and since our replaysOnErrorSampleRate value is set to 100%, Sentry detected it and sent it to us directly. By clicking on its content, we can learn more about the occurrence of the error or get detailed information. However, to keep it brief, I won’t go into that here. We received the error because we hadn’t defined Sentry. To resolve this, we add the code import * as Sentry from '@sentry/vue' to our script and click the button again. 🖱️

As you can see, we can also view the message we sent. One important aspect here is that we can see how many times this error occurred and how many users experienced it. The “Events” count shows how many times the error occurred, while the “Users” count indicates how many different users encountered this issue. By clicking into the error, we can access more detailed information. Essentially, we have successfully performed a basic error and data reporting process. Now, let’s move on to performance analysis.

Performance Monitoring

As you know, one of the important aspects for all of us is the page loading speed, in other words, the performance of our project. We mentioned that with Sentry, it is possible to analyze this performance. If we selected the Performance Monitoring option during the installation process, we actually gain some speed in the setup phase. When we return to our “main.js” file, we will see thee BrowserTracing and tranceSampleRate values. In BrowserTracing, the adjustments we make involve entering the addresses of our domains. “localhost” is set as the default. Additionally, we need to add the address of the deployed application.

I have added the example “https://moviepal.vercel.app" as you mentioned. This way, I will be able to measure its performance even in the deployed state.

Another value we have is tranceSampleRate, and it is recommended to lower this value in production environments. However, if you are doing local development, it is recommended to set this value to 1.0. This way, you will be able to analyze all page reloads.

How will performance monitoring be beneficial for us? Let’s see it in practice.

In fact, while working on this project, I was monitoring the performance metrics. And then I realized that the page loading was taking longer due to the images. I was using UseImage for this purpose, thinking it would be effective, but it doesn’t seem to be the case.

📌 I have shared the development examples I made here on Gist.

📌 The first thing I did here was to remove UseImage and use a regular Img tag to observe the situation.

📌 As you can see, there is some improvement in our metrics. Although the CLS value has increased, other parameters show a decrease of over 50%. Next, I enable the lazy loading feature of Swiper and the lazy attribute of the img tag. This leads to a significant decrease in our TTFB value.

📌 Then, as observed in the images, I notice that CSS files are being repeatedly imported and loaded within the components. I address this by globally importing them into the root directory of our project. This way, there will be no need to load them repeatedly on this page.

You can find a table below that shows the processes we do in a more comparable way.👇

	Swiper CSS Imported*	Event Duration	CLS	FCP	FP	LCP	TTFB	Gist
Swiper with UseImage	Yes	2.93s	0.226	733.4ms	733.4ms	1.207s	80.20ms	Gist
Swiper with Img Tag	Yes	2.67s	0.392	383.4ms	383.4ms	1.157s	35.60ms	Gist
Swiper with Img and Lazy	Yes	2.06s	0.253	391ms	391ms	791.5ms	18.60ms	Gist
Swiper with Img and Lazy	No	1.78s	0.218	312.9ms	312.9m	693.7ms	8ms	Gist

Swiper CSS Imported: Indicates whether the Swiper CSS is being reloaded within the page. If the value is “No”, it means that it has been imported into the project’s root directory as well.

If you feel that your knowledge about abbreviations and metrics is not sufficient, Google web.dev can be helpful for you.

As has seen, we created a simple example using Sentry’s Performance Monitoring tool and optimized our code. Of course, there are different optimization methods available, but here we made some basic improvements and significantly increased our page loading speed through Sentry.

With these optimizations, we were able to increase our page loading speed by approximately 60%.

In this article, I have tried to explain the usage and installation of Sentry and how it can be beneficial to us by providing examples.

After reading my post, feel free to reach out to me on my Linkedin account if you have any questions or suggestions.

See you in my next article! 📩