Optymalizacja pracy z projektami na GitHubie: zapoznanie się z Repozytorium Szablonów Github

Witam wszystkich, społeczność JavaRush! Dzisiaj porozmawiamy o otwartym kodzie źródłowym i o tym, czego potrzeba, aby stworzyć wysokiej jakości projekt OPRÓCZ pisanego kodu. Ważne jest, aby napisać przydatny produkt. Ale nie mniej ważne jest prawidłowe zaprojektowanie repozytorium (repozytorium projektu na GitHubie). Pomoże to w realizacji kolejnego kluczowego punktu - promocji produktu. Nawet jeśli projekt jest super fajny, ale jest źle zaprojektowany, nie jest opisany przynajmniej w README (o tym, czym jest README, możesz przeczytać tutaj ), nie jest podana licencja itp., to nie będzie sukcesu. Tyle, że nikt go nie zauważy. A jeśli ktoś to zauważy, nie będzie wiedział, jak z nim współdziałać. Jest wiele rzeczy, które trzeba wypełniać wielokrotnie i programiście nie jest łatwo kopiować i wklejać za każdym razem i właśnie w tym celu tego lata GitHub udostępnił funkcję Repozytorium szablonów , która pomaga w tym. Że tak powiem, aby zautomatyzować proces tworzenia nowych projektów. Dzisiaj zrozumiemy, czym jest repozytorium i czym jest repozytorium szablonów. Opiszemy, co poza kodem powinno znaleźć się w projekcie, na czym należy się skupić. Stwórzmy od zera Repozytorium Szablonów i dodajmy wszystko co potrzebne z mojego punktu widzenia. I na koniec, podczas tworzenia nowego repozytorium skorzystamy z Repozytorium Szablonów. Ale najpierw zrozummy warunki. Teoria: co powinno znajdować się w ogólnym repozytorium każdego projektu Każdy projekt open source na GitHubie powinien mieć dobrze opisany Profil Społeczności , który zawiera następujące elementy.

1. Szablon wydania

Tutaj należy opisać zasady tworzenia sprawy w repozytorium: jak ma się nazywać, jaka będzie etykieta, kto zostanie do niej przypisany. Podczas tworzenia nowego numeru dostępne będą następujące opcje:

• Raport o błędzie - utworzenie problemu opisującego wadę w projekcie;
• Zapytanie o funkcję - propozycja nowego pomysłu na projekt;
• Prośba o ulepszenie - propozycja ulepszeń projektu;
• Niestandardowy szablon wydania - jeśli inne opcje nie działają, możesz skorzystać z pustego szablonu.

Przykład tego, jak to wygląda, można zobaczyć tutaj .

2. Licencja

Licencja, na podstawie której napisany jest projekt. Konieczne jest, aby osoby korzystające z projektu wiedziały, co jest gwarantowane, a co nie. Na przykład licencja Apache 2.0 mówi, co następuje:

3.CZYTAJ

To opis projektu, jego wizytówka. Wszystko, co trzeba powiedzieć o projekcie, powinno się tu znaleźć. Oczywiście za każdym razem trzeba będzie to opisać, biorąc pod uwagę specyfikę projektu, ale nagłówki będą takie same. Na przykład:

• Przegląd – krótki opis projektu;
• Użycie - jak korzystać z projektu;
• Budynek - jak uruchomić projekt, co jest do tego potrzebne;
• Rozwiązywanie problemów — opisuje, jakie problemy możesz napotkać i jak je rozwiązać;
• Release Notes - opis zmian w zależności od wersji;
• Autorzy – nie zapomnijcie o swoich bliskich;
• Wkład - opis tego, w jaki sposób możesz uczestniczyć w rozwoju projektu;
• Kodeks Postępowania – opis zasad uczestnictwa;
• RELEASE_NOTES - plik, w którym zapisywane są wszystkie zmiany dla nowych wersji. Dobrą praktyką jest umieszczenie tego w osobnym dokumencie i zapisanie łącza w pliku README;
• CONTRIBUTING to plik opisujący, w jaki sposób możesz przyczynić się do rozwoju tego projektu. Wykonane jako oddzielny plik dla nagłówka Contributing w pliku README;
• CODE_OF_CONDUCT – plik opisujący zasady udziału w rozwoju projektu;
• Szablon Pull Request - szablon dla tych, którzy utworzą pull request.

Wszystkie te rzeczy są wykorzystywane od projektu do projektu, niezależnie od języka programowania i jego specyfiki.

Przećwicz: tworzenie własnego szablonu

Jak to mówią, przejdźmy od słów do czynów. Teraz na przykładzie pokażę Ci jak stworzyć własny szablon.

1. Pierwszą rzeczą, której potrzebujesz, jest konto na GitHubie/ zarejestruj się tam .

2. Utwórz nowe repozytorium: w tym celu kliknij + w prawym górnym rogu

3. Podczas tworzenia uzupełnij:

   • Nazwa repozytorium - w moim przypadku szablon-repozytorium;
   • Opis – krótki opis projektu;
   • Opuszczamy Publiczny, chociaż możesz wybrać Prywatny;
   • Zaznacz pole inicjalizacji README:

   • Wybierz licencję, w ramach której projekt będzie:

     Ponieważ w moim przypadku szablon jest ogólny, gitignore nie jest potrzebne: zostanie dodany dla konkretnego projektu i języka programowania.

     Dlatego kliknij Utwórz repozytorium , kończąc w ten sposób proces tworzenia. System automatycznie przeniesie nas do nowo utworzonego repozytorium.

4. Wypełnianie Profilu Społeczności : w utworzonym repozytorium przejdź do zakładki Insights i wybierz Społeczność :

   Jak widać, pozostaje tylko wypełnić Kodeks postępowania, Wkład, Szablon zgłoszenia i Szablon żądania ściągnięcia.

   Na przykładzie Kodeksu Postępowania pokażemy, jak dodać je do projektu.

   Kliknij przycisk Dodaj , system poprosi Cię o wybranie Porozumienia Współtwórcy lub Kodeksu Postępowania Obywatelskiego :

   Wybieram pierwszy i klikam Przejrzyj i prześlij .

   Następnie możesz edytować ten plik i zatwierdzić go.

   Na dole wybierz opcję Zatwierdź bezpośrednio do gałęzi głównej i kliknij Zatwierdź nowy plik :

   W rezultacie, jeśli wrócimy do profilu społeczności , okaże się, że Kodeks postępowania jest oznaczony jako dodany:

   Szablon wkładu i szablon wydania są dodawane w podobny sposób, więc nie będę tego pokazywać. Zrób to sam ;)

5. Dodaj szablon żądania ściągnięcia .

   Ale porozmawiajmy o tym osobno.

   Nie wiem, dlaczego GitHub nie dodał tej samej wygodnej opcji konfiguracji szablonu Pull-Request, więc będziesz musiał przestudiować dokumentację i dodać ją ręcznie.

   W tym celu kliknij Utwórz nowy plik w katalogu głównym repozytorium :

   Nazwa pliku powinna brzmieć: .github/pull_request_template.md .

   Dodajemy do szablonu to, czego potrzebujemy i klikamy Zatwierdź nowy plik , tak jak to zrobiliśmy powyżej. Nie zamierzałem wymyślać koła na nowo i znalazłem przykład , który wydawał mi się całkiem użyteczny.

   W ten sposób zostanie wypełniony cały profil społeczności:

6. Dodaj znacznik repozytorium szablonów .

   Aby to zrobić, przejdź do opcji Ustawienia w repozytorium i zaznacz pole, w którym jest napisane Repozytorium szablonów:

   I to wszystko, szablon do tworzenia nowych projektów jest gotowy. W ten sposób zaoszczędzimy dużo czasu w przyszłości, gdy będziemy musieli tworzyć nowe projekty. Pomoże Ci to również nie przegapić ważnych szczegółów, ponieważ często zdarza się, że zapomniałeś czegoś dodać, na przykład licencji lub przejrzystego szablonu sprawy.

Jak korzystać z repozytorium szablonów

Istnieją dwie opcje użycia:

1. Kiedy szablon jest Twoją bezpośrednią własnością: Podczas tworzenia nowego repozytorium będziesz mieć możliwość utworzenia na podstawie szablonu z listy szablonów, które posiadasz:

2. Gdy szablon jest obcy: tutaj również nie ma specjalnych problemów. Przejdź do tego szablonu i kliknij przycisk Użyj tego szablonu . Tutaj użyję animacji z oficjalnego dokumentu:

Podsumujmy to

W tym artykule przyjrzeliśmy się:

• czym jest repozytorium GitHub;
• czym jest repozytorium szablonów;
• co powinno znajdować się w repozytorium szablonów;
• jak stworzyć repozytorium szablonów;
• jak korzystać z Repozytorium Szablonów.

Oczywiście w oparciu o ten szablon można już stworzyć bardziej szczegółowe. Na przykład stworzyłem więcej szablonów z już skonfigurowanymi systemami kompilacji maven lub gradle . Co więcej: możesz utworzyć szablon repozytorium Spring Boot w oparciu o dwa ostatnie. Aby pogrupować wszystkie szablony, utworzyłem w GitHub organizację repozytorium szablonów zawierającą wszystkie szablony. Subskrybuj moje konto GitHub

Przydatne linki

• Organizacja ze wszystkimi szablonami, które stworzyłem
• Blog GitHub: Generuj nowe repozytorium za pomocą szablonów repozytoriów, jak utworzyć szablon dla repozytoriów
• Pomoc GitHub: Informacje o repozytoriach i dowiedz się, czym są repozytoria.
• Pomoc GitHub: Tworzenie repozytorium z szablonu jak stworzyć nowy projekt na podstawie szablonu
• Pomoc GitHub: Licencjonowanie repozytorium Opis licencjonowania projektów
• Pomoc GitHub: Utwórz opis repozytorium dotyczący tworzenia repozytorium
• Wskazówki dotyczące Open Source Guides dotyczące tworzenia/opisywania projektów open source.
• Pomoc GitHub: dodawanie szablonu pull-requestów - tworzenie szablonu pull-requestów.

Więcej moich artykułów

• Debugowanie w Intellij IDEA: przewodnik dla początkujących
• Przewodnik po tworzeniu klienta dla API Skyscanner i publikowaniu go w jCenter i Maven Central [Część 1]
• Przewodnik po tworzeniu klienta dla API Skyscanner i publikowaniu go w jCenter i Maven Central [Część 2]
• Tworzenie systemu monitorowania cen biletów lotniczych: przewodnik krok po kroku [Część 1]
• Tworzenie systemu monitorowania cen biletów lotniczych: przewodnik krok po kroku [Część 2]
• Tworzenie systemu monitorowania cen biletów lotniczych: przewodnik krok po kroku [Część 3]
• Rejestrowanie: co, jak, gdzie i czym?
• Jak test rozmowy kwalifikacyjnej zamienił się w bibliotekę open source
• Historia sukcesu. 20 godzin programowania tygodniowo, studia magisterskie i życie osobiste
• Jak znaleźć pracę? Wskazówki dotyczące wysyłania CV