Merge pull request #52 from JunoLab/avi/updateinstruction

add update instructions

docs/make.jl

@@ -16,17 +16,18 @@ makedocs(
             "man/installation.md",
             "man/basic_usage.md",
             "man/debugging.md",
-            "man/faq.md",
             "man/remote.md",
             "man/juno_frontend.md",
-            "man/info_developer.md"
+            "man/info_developer.md",
+            "man/update.md",
+            "man/faq.md",
         ],
         "Developer Documentation" => Any[
             "devdocs/contributor_guide.md",
             "devdocs/dev_install.md",
             "devdocs/ecosystem.md",
             "devdocs/test_suites.md",
-            "devdocs/communication.md"
+            "devdocs/communication.md",
         ]
     ]
 )

docs/src/devdocs/contributor_guide.md

@@ -5,7 +5,7 @@
 This project is composed of many sub-projects, and it can be hard to know the appropriate
 place to file issues. For that reason, we prefer that non-developers report issues
 on [Juno.jl GitHub repository](https://github.com/JunoLab/Juno.jl/issues) or
-at [Julia's discussion forum under the `Tooling ▶ Juno` category](https://discourse.julialang.org/c/tools/juno/l/latest).
+at [Julia Discourse under the `Tooling ▶ Juno` category](https://discourse.julialang.org/c/tools/juno/l/latest).
 If you know which package the issue is appropriate in, then please open an issue there.
 Bug reports can be some of the most helpful contributions!
 

docs/src/index.md

@@ -6,20 +6,25 @@ editor provided by GitHub. Juno consists of both Julia and Atom packages in orde
 add Julia-specific enhancements, such as syntax highlighting, a plot pane,
 integration with Julia's debugger, a console for running code, and much more.
 
-### Installation
+### Installation / Updates
 
 To install Juno, please see the [Installation Instructions](@ref). These installation
 instructions should work for Windows, Mac OSX, and Linux on the current Julia release (v1).
 If you wish to use Juno with the Julia nightly version, you may need to use the
 [Developer Installation Instructions](@ref).
 
-### Reporting Issues / Bugs
+Since Juno is under a rapid development, there will be lots of updates and
+you need to follow some steps to update Juno.
+When you update your Juno, please first read through [Update Instructions](@ref).
 
-If you have any issues with this setup, please do report them
+### Reporting Issues / Bugs / Discussions
+
+If you have any issues with this setup, look up for a [FAQ](@ref) section first.
+If it doesn't help, please do report them
 on [Juno.jl GitHub repository](https://github.com/JunoLab/Juno.jl/issues) or
-at [Julia's discussion forum under the `Tooling ▶ Juno` category](https://discourse.julialang.org/c/tools/juno/l/latest).
+at [Julia Discourse under the `Tooling ▶ Juno` category](https://discourse.julialang.org/c/tools/juno/l/latest).
 We'll do our best to help you get going.
-You can also ping us on [our Slack channel](https://julialang.slack.com/archives/C7JT7HQAD)
+You can also ping us on the `#juno-bridged` channel in [the Julia slack](https://slackinvite.julialang.org/)
 to ask some random questions or for a chat.
 
 ### User Manual
@@ -31,10 +36,13 @@ Juno, along with answer questions most new users encounter.
 Pages = [
     "man/installation.md",
     "man/basic_usage.md",
-    "man/faq.md",
+    "man/debugging.md",
     "man/remote.md",
-    "man/juno_frontend.md"
-    ]
+    "man/juno_frontend.md",
+    "man/info_developer.md",
+    "man/update.md",
+    "man/faq.md" 
+]
 Depth = 2
 ```
 

docs/src/man/faq.md

@@ -4,22 +4,18 @@
 
 Please leave bug reports either
 on [Juno.jl GitHub repository](https://github.com/JunoLab/Juno.jl/issues) or
-at [Julia's discussion forum under the `Tooling ▶ Juno` category](https://discourse.julialang.org/c/tools/juno/l/latest).
+at [Julia Discourse under the `Tooling ▶ Juno` category](https://discourse.julialang.org/c/tools/juno/l/latest).
+
+!!! note
+    When you report a problem, please add the output of `Julia Client: Debug Info` command or `Juno > Debug Information` menus entry if possible.
 
 ### Juno could not be started.
 
 Go to `Packages > Juno > Settings` and change `Julia Path` to point to the Julia binary.
 
-### The installation of some Atom packages fails. What can I do?
+### I have issues on update !
 
-It is possible that your Antivirus Software prevents certain files to be downloaded or
-executed that are necessary for Juno to function. Consider disabling antivirus software's
-real time monitoring for the duration of the installation. For certain scanners
-(Avast and McAffee) it might also be necessary to exclude
-```
-C:\Users\you\.atom\packages\julia-client\node_modules\node-pty-prebuilt\build\Release\winpty-agent.exe
-```
-from the real time monitoring after installation. This is an [upstream issue](https://github.com/rprichard/winpty/issues/142) which should hopefully be resolved soon.
+Please follow the steps described in [Update Instructions](@ref).
 
 ### Juno doesn't work properly after an Atom update. What do I do?
 
@@ -33,17 +29,6 @@ If so, click on it and then click on `Rebuild Packages`:
 
 Restart Atom and you should be good to go!
 
-### Juno doesn't work properly after some Atom packages were updated. What do I do?
-
-There's a chance the update of julia-client failed. To get a clean re-install
-while preserving any setting you might have changed, try the following steps:
-
-1. Close all Atom instances.
-2. Start a terminal (e.g. `cmd` on Windows or the Terminal App on MacOS)
-3. Execute `apm uninstall julia-client`.
-4. Execute `apm install julia-client`.
-5. Start Juno. Everything should work again.
-
 ### The integrated REPL/terminal is unbearably slow. How do I fix it?
 
 Enable the `Fallback Renderer` option in the `Terminal Options` in julia-client's settings

docs/src/man/installation.md

@@ -36,21 +36,23 @@ Type `uber-juno` into the search box and hit enter. Click the install button on
 Atom will then set up Juno for you, installing the required Atom and Julia packages.
 
 !!! note
-
     You may need to add the path to Julia if it is not accessible via the command `julia`.
     To do so, go to `Packages > Juno > Settings` and in the first box for `Julia Path`
     insert the path to your Julia installation
     (example: `C:\Users\UserName\AppData\Local\Julia-1.2.0\bin\julia.exe`)
 
 ## 4. Use Juno
 
-You should be good to go now -- try opening the REPL with `Packages > Juno > Open REPL`
+You should be good to go now -- try opening the REPL with `Juno > Open REPL`
 or `Ctrl-J Ctrl-O` (`Cmd-J Cmd-O` on macOS), and then press `Enter` in the REPL to start a Julia session.
 
 ## Troubleshooting
 
 If you experience problems after installing Juno, have a look at the [FAQ](@ref) section.
 In case you can't solve your problem with the instructions here or in the FAQ, then please post
 on [Juno.jl GitHub repository](https://github.com/JunoLab/Juno.jl/issues) or
-at [Julia's discussion forum under the `Tooling ▶ Juno` category](https://discourse.julialang.org/c/tools/juno/l/latest),
+at [Julia Discourse under the `Tooling ▶ Juno` category](https://discourse.julialang.org/c/tools/juno/l/latest),
 and we're happy to help.
+
+!!! note
+    When you report a problem, please add the output of `Julia Client: Debug Info` command or `Juno > Debug Information` menus entry if possible.

docs/src/man/update.md

@@ -0,0 +1,103 @@
+# Update Instructions
+
+To update your Juno, you need to follow the two steps –
+update both Atom packages and Julia packages,
+each of which constitutes a part of Juno.
+
+
+## 1. Update Atom Packages
+
+In this step, you install the latest versions of
+[`julia-client`](https://github.com/JunoLab/atom-julia-client) and
+[`ink`](https://github.com/JunoLab/atom-ink)
+packages.
+
+First, _**close all the Atom windows**_.
+
+And then type the following command into your terminal
+(e.g. `cmd` on Windows or the Terminal App on MacOS):
+
+```sh
+apm update
+```
+
+If that doesn’t work, or if you want to only update Juno-related packages,
+try the commands below instead:
+
+```sh
+apm uninstall ink
+apm uninstall julia-client
+apm install ink
+apm install julia-client
+```
+
+!!! note
+    To fully update Atom packages, an Atom process that had been started _before_ updating the packages needs to be restarted.
+    This is why we recommend you close all the Atom processes first.
+    If you follow the above step, `julia-client` and `ink` will be latest the next time you open Atom .
+
+!!! warning
+    It is possible that your Antivirus Software prevents certain files to be downloaded or
+    executed that are necessary for Juno to function. Consider disabling antivirus software's
+    real time monitoring for the duration of the installation. For certain scanners
+    (Avast and McAffee) it might also be necessary to exclude
+    ```
+    C:\Users\you\.atom\packages\julia-client\node_modules\node-pty-prebuilt\build\Release\winpty-agent.exe
+    ```
+    from the real time monitoring after installation. This is an [upstream issue](https://github.com/rprichard/winpty/issues/142) which should hopefully be resolved soon.
+
+## 2. Update Julia Packages
+
+Now you update Julia packages:
+[Atom.jl](https://github.com/JunoLab/Atom.jl) and
+[Juno.jl](https://github.com/JunoLab/Juno.jl).
+
+Start a Julia process _**outside of Juno**_, and then execute the following:
+
+```julia
+pkg> up Atom Juno
+```
+
+If it doesn't work, try to execute below and see what hinders the updates of
+Atom.jl and Juno.jl in your environment.
+
+```julia
+pkg> rm Atom Juno
+pkg> add Atom@atomjlver
+pkg> add Juno@junojlver
+```
+
+where `@atomjlver` and `@junojlver` is the versions of Atom.jl and Juno.jl that you're trying to update to, respectively.
+
+!!! tip
+    It is also possible to update Atom.jl and Juno.jl from Juno's REPL,
+    but in some update cases Juno's REPL itself may be unfunctional because of
+    the incompatibility between (already updated) Atom packages and (not-updated) Julia packages,
+    and so we recommend you update Julia packages outside of Juno.
+
+    Also note that when you update Julia packages from Juno's REPL
+    and if the `Boot Mode` config setting is set to `Cycler`,
+    you may need to restart Julia process _twice_ to reflect update changes.
+
+!!! warning
+    The versioning of Atom.jl and Juno.jl doesn't necessarily match.
+    For example, the current latest version of Atom.jl is `[email protected]`
+    while that of Juno.jl is `[email protected]`
+
+## 3. The New Juno is Ready !
+
+Congrat ! Now your Juno has been successfully updated.
+Let's start Atom, fire up Julia, and enjoy the new Juno !
+
+We usually publish release notes at [Julia Discourse](https://discourse.julialang.org/c/tools/juno/l/latest);
+please check there for what new features/improvements/bugfixes are included within a release.
+
+## Troubleshooting
+
+In a case you still face a problem even after following the update instructions here, then please post
+on [Juno.jl GitHub repository](https://github.com/JunoLab/Juno.jl/issues) or
+at [Julia Discourse under the `Tooling ▶ Juno` category](https://discourse.julialang.org/c/tools/juno/l/latest),
+and we're happy to help.
+
+!!! note
+    When you report a problem, please add the output of `Julia Client: Debug Info` command or `Juno > Debug Information` menus entry if possible.