Merge pull request #15 from DilumAluthge/dpa/zero-arg-authenticate-method

Make some breaking changes to the existing one-arg `authenticate(::AbstractString)` method, and add a new zero-arg `authenticate()` method

Author: pfitzseb

.github/workflows/CI.yml

@@ -1,17 +1,35 @@
 name: CI
 on:
-  - push
-  - pull_request
+  pull_request:
+    branches:
+      - master
+  push:
+    branches:
+      - master
+    tags: '*'
+concurrency:
+  # Skip intermediate builds: all builds except for builds on the `master` branch
+  # Cancel intermediate builds: only pull request builds
+  group: ${{ github.workflow }}-${{ github.ref }}-${{ github.ref != 'refs/heads/master' || github.run_number }}
+  cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
 jobs:
   test:
-    name: Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }} - ${{ github.event_name }}
     runs-on: ${{ matrix.os }}
+    timeout-minutes: 60
     strategy:
       fail-fast: false
       matrix:
         version:
+          # Parts of this package depend on Pkg internals.
+          # Because Pkg internals are allowed to change between Julia minor versions,
+          # we should run CI on each minor version of Julia that we want to support.
           - '1.3'
+          - '1.4'
           - '1.5'
+          - '1.6'
+          # - '1.7' # TODO: uncomment this line once Julia 1.8 is released
+          - '~1.8.0-rc1' # TODO: delete this line once Julia 1.8 is released
+          - '1' # automatically expands to the latest stable 1.x release
           - 'nightly'
         os:
           - ubuntu-latest
@@ -36,4 +54,8 @@ jobs:
             ${{ runner.os }}-test-
             ${{ runner.os }}-
       - uses: julia-actions/julia-buildpkg@v1
-      - uses: julia-actions/julia-runtest@v1
+      - uses: julia-actions/julia-runtest@v1
+      - uses: julia-actions/julia-processcoverage@v1
+      - uses: codecov/codecov-action@v2
+        with:
+          files: lcov.info

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2020 Julia Computing Inc.
+Copyright (c) 2020 Julia Computing Inc. and contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

Project.toml

@@ -1,7 +1,7 @@
 name = "PkgAuthentication"
 uuid = "4722fa14-9d28-45f9-a1e2-a38605bd88f0"
-authors = ["Sebastian Pfitzner"]
-version = "1.1.1"
+authors = ["Sebastian Pfitzner", "contributors"]
+version = "2.0.0-DEV"
 
 [deps]
 Downloads = "f43a241f-c20a-4ad4-852c-f6b1247861c6"
@@ -14,9 +14,3 @@ Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 Downloads = "1"
 JSON = "0.20, 0.21"
 julia = "1.3"
-
-[extras]
-Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
-
-[targets]
-test = ["Test"]

README.md

@@ -1,29 +1,71 @@
 # PkgAuthentication
 
-Authentication to private Julia package servers
+Interactive browser-based authentication to private Julia Pkg servers.
 
+## Setup
+
+#### Step 1: Make sure that PkgAuthentication.jl is installed in the default global Julia package environment (`v1.x`)
+
+```julia
+julia> delete!(ENV, "JULIA_PKG_SERVER")
+
+julia> import Pkg
+
+julia> Pkg.activate("v$(VERSION.major).$(VERSION.minor)"; shared = true)
+
+julia> Pkg.add("PkgAuthentication")
 ```
-    authenticate(pkgserver)
 
-Starts browser based pkg-server authentication (blocking).
+#### Step 2: Set the `JULIA_PKG_SERVER` environment variable
 
-`pkgserver` must be a URL pointing to a server that provides the `/pkgserver/challenge`,
-`/pkgserver/response`, and `/pkgserver/claimtoken` endpoints.
+One easy way to set the `JULIA_PKG_SERVER` environment variable is to add the following
+line to your [`startup.jl`](https://docs.julialang.org/en/v1/manual/getting-started/) file:
+
+```julia
+ENV["JULIA_PKG_SERVER"] = "my-pkg-server.example.com"
 ```
 
-## Installation
-1. Make sure PkgAuthentication.jl is part of the default Julia environment.
-2. Put the following into your `startup.jl` to enable authentication for server as configured in JULIA_PKG_SERVER environment variable.
+#### Step 3: Put the following snippet into your [`startup.jl`](https://docs.julialang.org/en/v1/manual/getting-started/) file
+
 ```julia
 # create a new anonymous module for the init code to not pollute the global namespace
 Base.eval(Module(), quote
-    using PkgAuthentication
-    PkgAuthentication.install()
+    import PkgAuthentication
+    PkgAuthentication.install();
 end)
 ```
 
+With the above snippet, Pkg will automatically prompt you when you need to authenticate.
+
+However, if you want to authenticate immediately (instead of waiting until the first
+Pkg operation that needs authentication), you can do so as follows. First, make
+sure that you have completed steps 1, 2, and 3 above. Then, open the Julia REPL
+and run the following:
+
+```julia
+julia> import PkgAuthentication
+
+julia> PkgAuthentication.authenticate();
+```
+
+## Adding new registries
+
+If you are using this private Pkg server for the first time, you probably want to
+make sure that you add any private registries that might be served by this Pkg server.
+
+First, make sure that you have completed steps 1, 2, and 3 above. Then, open the
+Julia REPL and run the following:
+
+```julia
+julia> import Pkg
+
+julia> Pkg.Registry.add()
+
+julia> Pkg.Registry.update()
+```
+
 ## Implementation
 
 Authentication is implemented with the following state machine:
 
-![structure](structure.png)
+![State machine](assets/structure.png)

structure.png renamed to assets/structure.png

@@ -1,6 +1,6 @@
 using LightGraphs, PkgAuthentication, GraphPlot, Cairo, Compose
 
-file = joinpath(@__DIR__, "src/PkgAuthentication.jl")
+file = joinpath(dirname(@__DIR__), "src", "PkgAuthentication.jl")
 
 g = SimpleDiGraph()
 lines = readlines(file)
@@ -19,4 +19,4 @@ for line in lines
     end
 end
 plot = gplot(g, nodelabel=vertices, linetype="curve")
-draw(PNG(joinpath(@__DIR__, "structure.png"), 16cm, 16cm), plot)
+draw(PNG(joinpath(@__DIR__, "structure.png"), 16cm, 16cm), plot)