cleaning

Author: Ducasse

Chapters/BasicClasses/BasicClasses.md

@@ -0,0 +1,35 @@
+### Configure your project nicely@sec:ConfigureVersioning code is just the first part of making sure that you and others can reload your code.Here, we describe how to define a Baseline, a project map that you will use to define dependencies within your project and dependencies to other projects. We also show how to add a good `.gitignore` file.In the next chapter, we will show how to configure your project to get more out of the services offered within the Github ecosystem, such as Github Actions to automatically execute your tests.We start by showing you how you can commit your code if you did not create your remote repository first. Then we show you how to you can configure Pharo to manage a github token to commit using HTTPS.![Creating a local repository without pre-existing remote repository.](figures/S12-NewRepository.png width=75&label=NewRepo)### What if I did not create a remote repositoryIn the previous chapter, we started by creating a remote repository on Github. Then we asked Iceberg to add a project by cloning it from Github. Now you may ask yourself what the process is to publish your project locally without a pre-existing repository. This is actually simple.#### Create a new repositoryWhen you add a new repository use the 'New repository' option as shown in *@NewRepo@*.#### Add a remoteIf you want to commit to a remote repository, you will have to add it using the _Repository_ browser. You can access this browser through the associated menu item or the icon.The _Repository_ browser gives you access to the `Git` repositories associated with your project: you can access, manage branches, and also add or remove remote repositories. Figure *@OpeningRepositoryBrowser@* shows the repository browser on our project.![Opening the repository browser let you add and browse branches as well as remote repositories.](figures/S13-OpeningRepository.png width=75&label=OpeningRepositoryBrowser)Pressing on the 'Add remote' iconic button adds a remote by filling the needed information that you can find in your Github project. Figure *@OpeningRepositoryBrowser@* shows it for the sample project using SSH and  Figure *@OpeningRepositoryBrowser2@* for HTTPS.![Adding a remote using the _Repository_ browser of your project \(SSH version\).](figures/S14-AddingRemote.png width=75&label=OpeningRepositoryBrowser)![Adding a remote using the _Repository_ browser of your project \(HTTP version\).](figures/S14-AddingRemote-HTTP.png width=75&label=OpeningRepositoryBrowser2)#### Push to the remoteNow you can push your changes and versions to the remote repository using the Push iconic button.Once you have pushed you can see that you have one remote as shown in Figure *@PushedFromReport@*.![Once you pushed you changes to the remote repository.](figures/S15-PushedFromReport.png width=75&label=PushedFromReport)### Configuring Pharo to commit in HTTPS/SSHWith recent version of github, you should use a token to connect using HTTPS to be able to commit to your repository.Now you can configure Pharo to store your token as well your github account authentification. In addition you can configure Pharo to point to your private and public SSH key as follows: ```StartupPreferencesLoader default executeAtomicItems: {
+    StartupAction 
+        name: 'Logo' 
+        code: [ PolymorphSystemSettings showDesktopLogo: false] .
+    StartupAction 
+        name: 'Git Settings' 
+        code: [ 
+            Iceberg enableMetacelloIntegration: true.
+            IceCredentialStore current
+                    storeCredential: (IcePlaintextCredentials new
+                    username: 'xxxxxJohnDoe';
+                    password: 'xxxPassOfJohnDoe';
+                    host: 'github.com';
+                    yourself).
+            IceCredentialsProvider sshCredentials
+                username: 'git';
+                publicKey: 'Path to your public rsa file (public key)';
+                privateKey: 'Path to your private rsa file (private key)'.
+            IceCredentialStore current
+                storeCredential: (IceTokenCredentials new
+                    username: 'xxxxxJohnDoe';
+                    token: 'magictoken here ';
+                    yourself) 
+                forHostname: 'github.com'.
+            ]. 
+}```You should place this file in the preference folder that depends on your OS. You can find this place by using the `Startup` menu. Note that you can configure this for all or one specific version of Pharo.### Defining a `BaselineOf`A _baseline_ is a description of the architecture of a project. You will express the dependencies between your packages and other projects so that all the dependent projects are loaded without the user having to understand them or the links between them.A baseline is expressed as a subclass of `BaselineOf` and packaged in a package named `'BaselineOfXXX'` \(where 'XXX' is the name of your project\). So if you have no dependencies, you can have something like this:```BaselineOf subclass: #BaselineOfMyCoolProjectWithPharo
+  ...
+  package: 'BaselineOfMyCoolProjectWithPharo'``````BaselineOfMyCoolProjectWithPharo >> baseline: spec
+  <baseline>
+  spec
+    for: #common
+    do: [ spec package: 'MyCoolProjectWithPharo' ]```Once you have defined your baseline, you should add its package to your project using the working copy browser as explained in the previous chapter. You should obtain the following situation shown in Figure *@WithBaseline@*. Now, commit it and push your changes to your remote repository.![Added the baseline package to your project using the _Working copy_ browser.](figures/WithBaseline.png width=75&label=WithBaseline)A more elaborated web resources about baseline possibility is available at: [https://github.com/pharo-open-documentation/pharo-wiki/](https://github.com/pharo-open-documentation/pharo-wiki/).### Loading from an existing repositoryOnce you have a repository you committed code to and would like to load it into a new Pharo image, there are two ways to work this out.#### Manual load- Add the project as explained in the first chapter- Open the working copy browser by double clicking on the project line in the repositories browser.- Select a package and manually load it.#### Scripting the loadThe second way is to make use of Metacello. However, this will only work if you have already created a `BaselineOf`. In this case, you can just execute the following snippet:```Metacello new
+  baseline: 'MyCoolProjectWithPharo';
+  repository: 'github://Ducasse/MyCoolProjectWithPharo/src';
+  load```For projects with metadata, like the one we just created, that's it.Notice that we not only mention the Github pass but also added the code folder \(here `src`\).### Going further:  Understanding the architectureAs `git` is a distributed versioning system, you need a local clone of your repository.In general you edit your working copy located on your hard-drive and you commit to your local clone, and from there you push to remote repositories like Github. We explain here the specificity of managing Pharo with git.When coding in Pharo, you should understand that you are not directly editing your local working copy, you are modifying objects that represent classes and methods that are living in the Pharo environment.Therefore it is like you have a double working copy: Pharo itself and the `git` working copy.When you use `git` command lines,  you have to understand that there is the code in the image and the code in the working copy \(and your local clone\).To update your image, you _first_ have to update your `git` working copy and _then_ load code from the working copy to the image. To save your code you have to save the code to files, add them to your git working copy and commit them to your clone.Now the interesting part is that Iceberg manages all this for you transparently.All the synchronization between these two working copies is done behind the scene.Figure *@architecture@* shows the architecture of the system.- You have your code in the Pharo image.- Pharo is acting as a working copy \(it contains the contents of the local `git` repository\).- Iceberg manages the publication of your code to the `git` working copy and the `git` local repository.- Iceberg manages the publication of your code to remote repositories.- Iceberg manages the re-synchronization of your image with the `git` local repository, `git` remote repositories and the `git` working copy.![Architecture.](figures/architecture.png width=75&label=architecture)### ConclusionWe show how to package your code correctly.It will help you to reload it.