To będzie tutorialowy wpis dla początkujących, ale mam nadzieję, że komuś się przyda. Mimo że nie dotyczy wprost projektu MemoryVisualizera, od początku istnienia konkursu obiecywałem sobie przygotować taki mini poradnik nt. jak rozpocząć nowy projekt na GitHub. Cel - tworzymy nowe repozytorium na GitHubie, commitujemy pierwsze zmiany, tworzymy brancha na jakiś feature. Potem go mergujemy. Przy okazji nauczymy się trochę używania gita i może jakiś innych, fajnych narzędzi. Ze względu na długość, poradnik podzielony jest na kilka części. W tej stworzymy repozytorium i zaczniemy je lokalnie modyfikować.
Już na samym początku stajemy przed wyborem - czy używamy głównie command line Gita, okienkowego programu GitHub Desktop czy też stron online GitHuba. Ja skupię się na swojej propozycji, w której użyjemy wszystkiego po trochu.
Tworzenie repozytorium
Zaczynamy oczywiście od założenia konta na GitHub.com, ale to oczywista oczywistość. Po zalogowaniu, w prawym, górnym rogu klikamy na plusik i wybieramy New repository.
Naszym oczom pojawi się kilka opcji związanych z repozytorium, wśród których najważniejsza jest oczywiście nazwa:
Repozytorium w wersji darmowej musi być publiczne, na prywatne możemy sobie pozwolić w wersji płatnej - najtaniej będzie to 7 dolarów miesięcznie. Polecam też zaznaczenie opcji Initialize this repository with README dzięki czemu uzyskamy w repozytorium szablon owego pliku. Po kliknięciu Create repository, wszystko będzie od razu gotowe i wylądujemy w panelu naszego repozytorium:
Jak widać wszystko da się tu zrobić online - np. dodać nowy plik. Możemy też online edytować pliki (np. README.md) ale my zrobimy to lepiej...
Dlatego następnie proponuję ściągnąć wspomniany GitHub Desktop. Dodatkową zaletą jest, że zainstaluje on również wersję command line Gita, co przyda się później. W trakcie instalacji zostaniemy poproszeni o podanie danych swojego konta:
Prawdopodobnie w ostatnim kroku pojawi się nam okienko, mówiące że nie posiadamy żadnego lokalnego repozytorium:
Wybieramy opcję dashboard i startujemy! Z lewego górnego rogu klikamy w widoczny plusik, z listy wybieramy nasze konto, opcję Clone:
W następnym kroku podajemy miejsce, w którym zostanie utworzony katalog z naszym repozytorium, klikamy OK i gotowe! Jeśli przejdziemy do nowo utworzonego katalogu, ujrzymy tam skromną zawartość naszego repozytorium:
W tym momencie jesteśmy gotowi, by rozpocząć prace na naszym lokalnym "kodzie".
Plik readme
Zaczniemy od sprawy banalnej, ale nauczymy się przy okazji co nieco. Jak zauważyliście, plik README ma rozszerzenie md, od Markdown, czyli składni pozwalającej formatować tekst. Możemy dodawać pogrubienia, nagłówki, obrazki i wiele innych. Spotkaliście się zapewne z czymś takim np. na forach internetowych. Dobry opis tej składni znajduje się na stronach GitHuba.
Wyedytujmy zatem plik README.md (w dowolnym edytorze teskstowym), tak by zawierał trochę podstawowych elementów:
# NEverything
NEverything library lets you create **everything** you want, just straigt from the code.
## Introduction
This is really great library. And it contains GitHub logo, downloaded from... [GitHub](https://github.com/logos), what makes it event better:
## Examples
If we do not want to use simple `NEverything.CreateAllWhatIWant().Run()`, we can be more precise. For example, in C#:
```csharp
var moneyGenerator = NEverything.CreateWhatIWant(_ => CreatesMoney());
var money = moneyGnerator.Run();
```
Jedną z mniej oczywistych kwestii jest załączanie obrazków. Ponieważ muszą być one wklejane poprzez odnośnik, pozostaje pytanie gdzie je fizycznie umieszczać. Najczęściej, jeśli jest ich mało, znajdują się ona w katalogu głównym repozytorium. Jeśli mamy w projekcie folder zawierający dokumentację, czasem obrazki są linkowane właśnie stamtąd. Najrzadziej zdarza się linkowanie do zewnętrznych zasobów - np. logo produktu. Pamiętajmy, że plik README.md jest częścią naszego projektu, tak samo jak obrazki. Powinny stanowić zamkniętą całość i nie być za duże - gdy w przyszłości ktoś będzie forkował nasz projekt, bez sensu by ściągał megabajty mediów. Mimo rozbudowanych możliwości składnia Markdown, pliki md pozostają plikami readme, a nie pełnoprawnymi stronami internetowymi! W powyższym przykładzie linkuję do nowego folderu i pliku, muszę więc pamiętać je lokalnie utworzyć.
BTW. lista rozpoznawalnych języków dla bloków kodu, dostępna jest w dokumentacji GitHuba.
Gratuluję! Stworzyliśmy projekt i dokonaliśmy w nim zmian. Nie pozostaje nic innego jak wysłać je do GitHuba, czego dokonamy w części drugiej.