From 7bcbe2989d91cdec8d70216b78da9f86d998b24e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?St=C3=A9phaneDucasse?= Date: Thu, 16 May 2024 08:29:24 -0400 Subject: [PATCH] fixing some typos --- Chapters/Git/git_practical.md | 1 - Chapters/Started/extensions.md | 14 +-- Chapters/Started/glossary.md | 110 ++++++++++++++++++- Chapters/Started/pharo.md | 36 +++--- Chapters/Started/services.md | 73 +++++++++++-- Chapters/Started/started.md | 193 ++++++++++++++++++++++++++++++++- Chapters/Tips/tips.md | 46 +++++++- 7 files changed, 433 insertions(+), 40 deletions(-) diff --git a/Chapters/Git/git_practical.md b/Chapters/Git/git_practical.md index 9bb1fc8..2cac58c 100644 --- a/Chapters/Git/git_practical.md +++ b/Chapters/Git/git_practical.md @@ -254,7 +254,6 @@ Connect yourself to your Github settings and go to the "SSH and GPG keys" menu. ### Rewriting the History - Many times it happens that we accidentally commit something wrong. Maybe we wanted to commit more or less things, maybe a completely different content, or we did a mistake in the commit's message. In these cases, we can rewrite Git's history, e.g, undo our current commit and go back to the previous commit, or rewrite the current commit with some new properties. diff --git a/Chapters/Started/extensions.md b/Chapters/Started/extensions.md index 82e7c62..e6ef568 100644 --- a/Chapters/Started/extensions.md +++ b/Chapters/Started/extensions.md @@ -5,7 +5,7 @@ Versioning code is just the first part of making sure that you and others can re In this chapter 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 Travis-ci to execute automatically your tests. +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 Travis-ci to execute automatically your tests. We start by showing you how you can commit your code if you did not create your remote repository first. @@ -14,9 +14,9 @@ We start by showing you how you can commit your code if you did not create your ### What if I did not create a remote repository -In 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 is the process to publish first your project locally without a pre-existing repository. This is actually simple. +In 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 about the process to publish first your project locally without a pre-existing repository. This is actually simple. #### Create a new repository. @@ -32,7 +32,7 @@ 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. +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) @@ -146,7 +146,7 @@ Metacello new 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`). +Notice that we not only mention the GitHub pass but also added the code folder (here `src`). ### \[Optional\] Add a nice .gitignore file @@ -181,7 +181,7 @@ github-*.zip As `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. +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. diff --git a/Chapters/Started/glossary.md b/Chapters/Started/glossary.md index 320581f..f8c51a3 100644 --- a/Chapters/Started/glossary.md +++ b/Chapters/Started/glossary.md @@ -1,4 +1,60 @@ -## Iceberg Glossary Git is complicated. Git with \(Pharo\) images is even more complicated. This page introduces the vocabulary used by Iceberg. Part of this vocabulary is Git vocabulary, part of it is Github's vocabulary, part of it is introduced by Iceberg. ### Git #### Disk Working Copy \(Git\) It is important not to confuse the code on your disk with the one of the repository itself. The repository \(a kind of database\) has a lot more information, such as known branches, history of commits, remote repositories, the git index and much more. Normally this information is kept in a directory named .git. The files that you see on your disk and that you edit are just a working copy of the contents in the repository. #### The git index \(Git\) The index is an intermediate structure which is used to select the contents that are going to be committed. So, to commit changes to your local repository, two actions are needed: 1. `git add someFileOrDirectory` will add `someFileOrDirectory` to the index. 1. `git commit` will create a new commit out of the contents of the index, which will be added to your local repository and to the current branch. When using Iceberg, you normally do not need to think about the index, Iceberg will handle it for you. However, you might need to be aware that the index is part of the git repository, so if you have other tools working with the same repository there might be conflicts between them. #### Local and remote repositories \(Git\) To work with Git you always need a local repository \(which is different from the code you see on your disk, that is not the repository, that is just your working copy\). Remember that the local repository is a kind of a code database. Most frequently your local repository will be related with one remote repository which is called origin and will be the default target for pull and push. #### Upstream \(Git\) The upstream of a branch is a remote branch which is the default source when you pull and the default target when you push. Most probably it is a branch with the same name in your origin remote repository. #### Commit-ish \(Git\) A commit-ish is a reference that specifies a commit. Git command line tools usually accept several ways of specifying a commit, such as a branch or tag name, a SHA1 commit id, and several fatality-like combinations of symbols such as HEAD^, @{u} or master\~2. The following table contains examples for each commit-ish expression. A complete description of the ways to specify a commit \(and other git objects\) can be found [here](https://mirrors.edge.kernel.org/pub/software/scm/git/docs/gitrevisions.html#_specifying_revisions). ``` ---------------------------------------------------------------------- +## Iceberg Glossary + + +Git is complicated. Git with (Pharo) images is even more complicated. +This page introduces the vocabulary used by Iceberg. +Part of this vocabulary is Git vocabulary, part of it is Github's vocabulary, part of it is introduced by Iceberg. + +### Git + +#### Disk Working Copy (Git) + + +It is important not to confuse the code on your disk with the one of the repository itself. +The repository (a kind of database) has a lot more information, such as known branches, history of commits, remote repositories, the git index and much more. +Normally this information is kept in a directory named .git. +The files that you see on your disk and that you edit are just a working copy of the contents in the repository. + + +#### The git index (Git) + + +The index is an intermediate structure which is used to select the contents that are going to be committed. + +So, to commit changes to your local repository, two actions are needed: + +1. `git add someFileOrDirectory` will add `someFileOrDirectory` to the index. +1. `git commit` will create a new commit out of the contents of the index, which will be added to your local repository and to the current branch. + + +When using Iceberg, you normally do not need to think about the index, Iceberg will handle it for you. +However, you might need to be aware that the index is part of the git repository, so if you have other tools working with the same repository there might be conflicts between them. + +#### Local and remote repositories (Git) + + +To work with Git you always need a local repository (which is different from the code you see on your disk, that is not the repository, that is just your working copy). +Remember that the local repository is a kind of a code database. + +Most frequently your local repository will be related with one remote repository which is called origin and will be the default target for pull and push. + +#### Upstream \(Git\) + + +The upstream of a branch is a remote branch which is the default source when you pull and the default target when you push. +Most probably it is a branch with the same name in your origin remote repository. + +#### Commit-ish \(Git\) + + +A commit-ish is a reference that specifies a commit. +Git command line tools usually accept several ways of specifying a commit, such as a branch or tag name, a SHA1 commit id, and several fatality-like combinations of symbols such as `HEAD^`, `@{u}` or `master\~2`. + +The following table contains examples for each commit-ish expression. +A complete description of the ways to specify a commit (and other git objects) can be found [here](https://mirrors.edge.kernel.org/pub/software/scm/git/docs/gitrevisions.html#_specifying_revisions). + +``` +---------------------------------------------------------------------- | Format | Examples ---------------------------------------------------------------------- | 1. | dae86e1950b1277e545cee180551750029cfe735 @@ -15,4 +71,54 @@ | 12. ^{} | v0.99.8^{} | 13. ^{/} | HEAD^{/fix nasty bug} | 14. :/ | :/fix nasty bug ----------------------------------------------------------------------- ``` ### Iceberg #### Iceberg Working Copy \(Iceberg\) Iceberg also includes an object called the working copy that is not quite the same as Git's working copy. Iceberg's working copy represents the code loaded in the Pharo image, with the loaded commit and the packages. #### Local Repository Missing \(Iceberg\) The Local Repository Missing status is shown by iceberg when a project in the image does not find its repository on disk. This happens most probably because you have downloaded an image that somebody else created, or you deleted/moved a git repository in your disk. Most of the times this status is not shown because iceberg automatically manages disk repositories. To recover from this status, you need to update your repository by cloning a new git repository or by configuring an existing repository on disk. #### Fetch required. Unknown ... \(Iceberg\) The Fetch required status is shown by Iceberg when a project in the image was loaded from a commit that cannot be found in its local repository. This happens most probably because you've downloaded an image that somebody else created, and/or your repository on disk is not up to date. To recover from this status, you need to fetch from remotes to try to find the missing commit. It may happen that the missing commit is not in one of your configured remotes \(even that nobody ever pushed it\). In that case, the easiest solution is to discard your image changes and checkout an existing branch/commit. #### Detached Working Copy \(Iceberg\) The Detached working Copy status is shown by Iceberg when a project in the image was loaded from a commit does not correspond with the current commit on disk. This happens most probably because you've modified your repository from the command line. To recover from this status, you need to align your repository with your working copy. Either you can 1. discard your image changes and load the repository commit, 1. checkout a new branch pointing to your working copy commit or 1. merge what is in the image into the current branch. #### Detached HEAD \(Git\) The Detached HEAD status means that the current repository on disk is not working on a branch but on a commit. From a git stand-point you can commit and continue working but your changes may get lost as the commit is not pointed to by any branch. From an Iceberg stand-point, we forbid commit in this state to avoid difficult to understand and repair situations. To recover from this status, you need to checkout a \(new or existing\) branch. \ No newline at end of file +---------------------------------------------------------------------- +``` + + +### Iceberg + + +#### Iceberg Working Copy (Iceberg) + + +Iceberg also includes an object called the working copy that is not quite the same as Git's working copy. +Iceberg's working copy represents the code loaded in the Pharo image, with the loaded commit and the packages. + +#### Local Repository Missing (Iceberg) + + +The Local Repository Missing status is shown by iceberg when a project in the image does not find its repository on disk. +This happens most probably because you have downloaded an image that somebody else created, or you deleted/moved a git repository in your disk. +Most of the times this status is not shown because iceberg automatically manages disk repositories. + +To recover from this status, you need to update your repository by cloning a new git repository or by configuring an existing repository on disk. + +#### Fetch required. Unknown ... (Iceberg) + + +The Fetch required status is shown by Iceberg when a project in the image was loaded from a commit that cannot be found in its local repository. +This happens most probably because you've downloaded an image that somebody else created, and/or your repository on disk is not up to date. + +To recover from this status, you need to fetch from remotes to try to find the missing commit. +It may happen that the missing commit is not in one of your configured remotes \(even that nobody ever pushed it\). +In that case, the easiest solution is to discard your image changes and checkout an existing branch/commit. + +#### Detached Working Copy (Iceberg) + + +The Detached working Copy status is shown by Iceberg when a project in the image was loaded from a commit does not correspond with the current commit on disk. +This happens most probably because you've modified your repository from the command line. + +To recover from this status, you need to align your repository with your working copy. +Either you can +1. discard your image changes and load the repository commit, +1. checkout a new branch pointing to your working copy commit or +1. merge what is in the image into the current branch. + + +#### Detached HEAD (Git) + + +The Detached HEAD status means that the current repository on disk is not working on a branch but on a commit. From a git stand-point you can commit and continue working but your changes may get lost as the commit is not pointed to by any branch. +From an Iceberg stand-point, we forbid commit in this state to avoid difficult to understand and repair situations. +To recover from this status, you need to checkout a \(new or existing\) branch. diff --git a/Chapters/Started/pharo.md b/Chapters/Started/pharo.md index b940868..22440e7 100644 --- a/Chapters/Started/pharo.md +++ b/Chapters/Started/pharo.md @@ -3,7 +3,7 @@ Pharo itself is hosted on GitHub under [http://www.github.com/pharo-project/](http://www.github.com/pharo-project/). All the development of the core system is done via this code repository. -You can contribute to Pharo itself fixing some issues. +You can contribute to Pharo itself by fixing some issues. The official and unique way of submitting code is by doing a _Pull Request_ from your fork to the official repository. @@ -15,8 +15,8 @@ You can see the issues on the Pharo Github repository: [http://www.github.com/ph The general process is summarised by the following steps: 1. Download the latest version (this is important since I will make sure that you do not have to resync your fork). -1. Use repair (it will fetch some commits and make sure that your local repository is in sync the remotes). -1. Use repair (and create a branch let us called Bottom-123 that will point to the commits of your image). +1. Use repair (it will fetch some commits and make sure that your local repository is in sync with the remotes). +1. Use repair (and create a branch -- let us called it Bottom-123 -- that will point to the commits of your image). 1. Create a new branch for the issue you want to work on. 1. Code, then commit, then push to YOUR fork 1. Issue a PullRequest from your fork to Pharo @@ -27,24 +27,22 @@ The general process is summarised by the following steps: ### Step 0: Setting up the development environment -Download and launch latest Pharo version: +Download and launch the latest Pharo version: -The recommended way to download Pharo is to use the Pharo launcher, which you can get from Pharo download's page. Otherwise, if you have a nice command line environment (wget, readline, bash), download latest development pharo using zeroconf. +The recommended way to download Pharo is to use the Pharo launcher, which you can get from Pharo download's page. -!!note Pro tip: If you're on windows and you want a nice command line environment, install msys +!!note Pro tip: If you're on Windows and you want a nice command line environment, install msys + +else you can try the following patterned expression: ``` -wget -O- get.pharo.org/64/90+vm | bash +curl https://get.pharo.org/[32/64]/[version]+vm | bash ./pharo-ui Pharo.image ``` +If you don't have a command line environment, you can download both image and vm manually from the following links for example: [http://files.pharo.org/get-files/120/]([http://files.pharo.org/get-files/120/) -If you don't have a command line environment, you can download both image and vm manually from the following links for windows for example: - -- Image: http://files.pharo.org/get-files/90/pharo.zip -- VM: http://files.pharo.org/get-files/90/pharo-win-stable.zip - -Or you can browse the file server and find the files suiting your environment. +Browse the file server and find the files that suit your environment. ### Fork the Pharo repository @@ -123,8 +121,8 @@ The repair menu item/button will propose you some solutions. And clicking on the **Repair repository** menu will show you the repair view, showing an explanation of the current situation and some proposed solutions: -- Locate this repository in your file system: if you have already cloned your pharo fork repository on your disk you can simply point to it. Pharo will synchronise it as explained in the next steps. -- Clone again this repository: you can clone again your Pharo fork from github to your local disc. Again your fork may be desynchronised from the actual Pharo version but Iceberg will manage it too. +- Locate this repository in your file system: if you have already cloned your pharo fork repository on your disk you can simply point to it. Pharo will synchronize it as explained in the next steps. +- Clone again this repository: you can clone again your Pharo fork from GitHub to your local disc. Again your fork may be desynchronized from the actual Pharo version but Iceberg will manage it too. So depending on the action you chose: you can then choose to search in your disk for an existing clone or to clone your forked Pharo repository. @@ -145,7 +143,7 @@ To solve again, launch the repair action again. Usually, if you already have all **Detached Working Copy** means that the image commit does not correspond with the repository commit (more details of it in the Glossary). At this point, we need to synchronize both to be able to work. -Most of the times, the easier thing to do in this case is to just create a new branch as suggested in the Pro Tip before. If you plan to only fix on issue and you already know which issue you'll be working on, you can create a branch using the "New branch from issue" option. Otherwise, a nice alternative is to create a temporary branch like temp/synch that you can later on remove. +Most of the time, the easier thing to do in this case is to just create a new branch as suggested in the Pro Tip before. If you plan to only fix on issue and you already know which issue you'll be working on, you can create a branch using the "New branch from issue" option. Otherwise, a nice alternative is to create a temporary branch like temp/synch that you can later on remove. ![Solving the detached working copy situation.](figures/Contribute4-DetachedWorkingCopy.png width=65&label=detached) @@ -155,12 +153,12 @@ Most of the times, the easier thing to do in this case is to just create a new b Pick up or create an issue and fix it. Once you have modifications in your image, it's time to push those changes to _your_ fork and make a pull request from your fork to the main Pharo repository. To do that, we enforce the following process: - you create a local branch for the issue, -- you issue a pull request of that issue to the main pharo development branch. +- you issue a pull request of that issue to the main Pharo development branch. -Once you have done and commited all your work, you need to push it and create a pull request. Right click on the repository and go to the Github plugin menu item. +Once you have done and committed all your work, you need to push it and create a pull request. Right click on the repository and go to the Github plugin menu item. -Select the option **Create pull request** and select as target branch pharo's development branch. +Select the option **Create pull request** and select as target branch Psssharo's development branch. And issue the pull request! diff --git a/Chapters/Started/services.md b/Chapters/Started/services.md index 909ffce..4ac6038 100644 --- a/Chapters/Started/services.md +++ b/Chapters/Started/services.md @@ -1,9 +1,31 @@ -## Empowering your projects Now that you can save your code on Github in a breeze, you can take advantage of services to automate actions. For example, to execute tests using [Travis](http://www.travis-ci.com)\) or [AppVeyor](https://www.appveyor.com) for Windows. ### Adding Travis integration By adding two simple files, you can have the tests of your project automatically run after each commit with Travis. You need to enable Travis in your Github repository. Since Travis is changing its policy and work tightly in relation with Github you might have a better time checking on their respective websites. You should also add the two following files: `.travis.yml` and `.smalltalk.ston` in the top level of your repository. `.travis.yml` ``` language: smalltalk +## Empowering your projects + + +Now that you can save your code on GitHub in a breeze, you can take advantage of services +to automate actions. For example, to execute tests using [Travis](http://www.travis-ci.com)\) or [AppVeyor](https://www.appveyor.com) for Windows. + +### Adding Travis integration + + +By adding two simple files, you can have the tests of your project automatically run after each commit with Travis. You need to enable Travis in your GitHub repository. Since Travis is changing its policy and work tightly in relation with GitHub you might have a better time checking on their respective websites. + +You should also add the two following files: `.travis.yml` and `.smalltalk.ston` in the top level of your repository. + +`.travis.yml` + +``` +language: smalltalk sudo: false os: - linux smalltalk: - - Pharo-7.0 ``` `.smalltalk.ston` ``` SmalltalkCISpec { + - Pharo-7.0 +``` + + +`.smalltalk.ston` +``` +SmalltalkCISpec { #loading : [ SCIMetacelloLoadSpec { #baseline : 'MyCoolProjectWithPharo', @@ -11,7 +33,18 @@ smalltalk: #platforms : [ #pharo ] } ] -} ``` If you have done everything right, Travis will pick up the changes and will start testing and building your project… and you are done, congratulations! ### On windows If you want to make sure that your code runs on windows, you should use the Appveyor service and add the `appveyor.yml` file. ``` environment: +} +``` + + +If you have done everything right, Travis will pick up the changes and will start testing and building your project… and you are done, congratulations! + +### On windows + +If you want to make sure that your code runs on Windows, you should use the Appveyor service and add the `appveyor.yml` file. + +``` +environment: CYG_ROOT: C:\cygwin CYG_BASH: C:\cygwin\bin\bash CYG_CACHE: C:\cygwin\var\cache\setup @@ -27,19 +60,31 @@ platform: install: - '%CYG_EXE% -dgnqNO -R "%CYG_ROOT%" -s "%CYG_MIRROR%" -l "%CYG_CACHE%" -P unzip' - - ps: Start-FileDownload "https://Github.com/hpi-swa/smalltalkCI/archive/master.zip" "C:\smalltalkCI.zip" + - ps: Start-FileDownload "https://GitHub.com/hpi-swa/smalltalkCI/archive/master.zip" "C:\smalltalkCI.zip" - 7z x C:\smalltalkCI.zip -oC:\ -y > NULL build: false test_script: - - '%CYG_BASH% -lc "cd $APPVEYOR_BUILD_FOLDER; exec 0