Mercurial > hg > LGDataverses

annotate doc/mergeParty/readme.md @ 10:a50cf11e5178

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Rewrite LGDataverse completely upgrading to dataverse4.0
author Zoe Hong <zhong@mpiwg-berlin.mpg.de>
date Tue, 08 Sep 2015 17:00:21 +0200
parents
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
10
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
1 # Merge Party Readme
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
2 Welcome to the merge party! This document is intended to give a short overview of why we need this party, when was changed and how to change it. There's much work to do, so we'll keep it short. Hopefully.
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
3
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
4 ## What Just Happened
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
5 In order to allow users to log into Dataverse using credentials from other systems (e.g. institutional Shibboleth server), we had to refactor out the internal user management sub-system (formerly known as "DataverseUser") and introduce a new user system. The existing system was taken out of Dataverse but kept in the .war file, as we also need to support standalone instances.
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
6
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
7 Put another way, we now ship Dataverse and a small identity provider in the released .war file. Here's a diagram:
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
8
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
9 ![Before and After](images/before-after.png "Master vs. Auth structure")
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
10
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
11 Since this is the equivalent of turning a chocolate chip cookie into a butter cookie and chocolate bar, much of the system's code was affected (a.k.a ripple effect). Hence the merge party.
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
12
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
13 The internal user object, the one that submits commands to the command engine, is now of type `edu.harvard.iq.dataverse.authorization.users.User`. Currently there are two subclasses of it: `GuestUser`, which does not live in the DB, and `AuthenticatedUser`, which does. Both can issue commands, have roles assigned to them, etc. The existence of the `GuestUser` class allows us to keep the invariant *the system always has a User*.
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
14
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
15 From a merge standpoint, this means that code that previously referenced `DataverseUser` needs to reference `User` now. If you know for sure an activity cannot ever be done by a guest user, you can reference `AuthenticatedUser`, and have the compiler impose this limitation for you at compile time (yay!).
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
16
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
17 Most of these changes have been done by Michael/Phil - otherwise, the `auth` branch would not compile.
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
18
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
19 Since the guest user does not live in the database, it does not have an id. Moreover, JPA classes cannot link directly to it\*. But have no fear - all users (and, really, all `RoleAssignee`s, which are users or groups) have an identifier. When you need to reference a user (and later, a group) just use the identifier (it's of type `String`). When needing to convert an identifier to a user, call `RoleAssigneeServiceBean.getRoleAssignee( identifier )` in the general case, or `AuthenticationServiceBean.getAuthenticatedUser(identifier)` if you're certain the identifier is of an authenticated user.
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
20
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
21
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
22 \* We have debated this for a while, since we could have created a dummy record, like we've done so far. We went with this solution, as it is cleaner, can't be messed up by SQL scripts, and will make even more sense once groups arrive.
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
23
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
24 ## How to Fix
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
25
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
26 While merging, you will encounter this situation:
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
27
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
28 ```java
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
29 <<<<<<< HEAD
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
30 code with new functionality or bug fixes, that uses the old user system
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
31 =======
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
32 code with old functionality that uses the new user system
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
33 >>>>>>> origin
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
34 ```
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
35
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
36 So, there's no "keep the latest code and remove the old one" here - there is some real merging to be done.
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
37
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
38 For example, we go from this:
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
39 ```java
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
40 @GET
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
41 @Path("{id}/versions")
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
42 public Response listVersions( @PathParam("id") Long id, @QueryParam("key") String apiKey ) {
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
43 DataverseUser u = userSvc.findByUserName(apiKey);
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
44 if ( u == null ) return errorResponse( Status.UNAUTHORIZED, "Invalid apikey '" + apiKey + "'");
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
45 ```
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
46
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
47 To this:
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
48 ```java
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
49 @GET
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
50 @Path("{id}/versions")
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
51 public Response listVersions( @PathParam("id") Long id, @QueryParam("key") String apiKey ) {
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
52 User u = builtinUserSvc.findByIdentifier(apiKey);
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
53 if ( u == null ) return errorResponse( Status.UNAUTHORIZED, "Invalid apikey '" + apiKey + "'");
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
54 ```
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
55
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
56 Testing for guest-ness of the user has changed as well. Before, when we had a dummy guest user, we used
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
57
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
58 ```xml
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
59 <ui:fragment rendered="#{dataverseSession.user.guest}">
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
60 ```
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
61
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
62 Now, we can query the user object about it's authentication state. So te code becomes:
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
63
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
64 ```xml
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
65 <ui:fragment rendered="#{!dataverseSession.user.authenticated}">
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
66 ```
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
67 Note that before we were asking `isGuest` and now we ask `isAuthenticated`, so the logic is reversed and we need to add a not operator. Sorry about that.
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
68
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
69 ### Tools
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
70
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
71 `git ls-files --unmerged`: show which files have not been merged
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
72
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
73 ## Other Added Things
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
74
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
75 ### Settings bean
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
76 Settings (in `edu.harvard.iq.dataverse.settings`) are where the application stores its more complex, admin-editable configuration. Technically, its a persistent `Map<String,String>`, that can be accessed via API (`edu.harvard.iq.dataverse.api.Admin`, on path `{server}/api/s/settings`). Currenly used for the signup mechanism.
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
77
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
78 ### Admin API
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
79 Accessible under url `{server}/api/s/`, API calls to this bean should be editing confugurations, allowing full indexing and more. The idea behing putting all of them under the `/s/` path is that we can later block these calls using a filter. This way, we could, say, allow access from localhost only. Or, we could block this completely based on some environemnt variable.
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
80
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
81 ### `setup-all.sh` script
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
82 A new script that sets up the users and the dataverses, sets the system up for built-in signup, and then indexes the dataverses using solr. Requires the [jq utility](http://stedolan.github.io/jq/). On Macs with [homebrew](http://brew.sh) installed, getting this utility is a `brew install jq` command away.
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
83
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
84
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
85 ## Undoing the undoing the merge
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
86 When merging back to master, we need to undo commit 8ae3e6a482b87b52a1745bb06f340875803d2c5b (a.k.a 8ae3e6a), which is the commit that undid the erroneous merge.
a50cf11e5178 Rewrite LGDataverse completely upgrading to dataverse4.0
Zoe Hong <zhong@mpiwg-berlin.mpg.de>
parents:
diff changeset
87 More at http://www.christianengvall.se/undo-pushed-merge-git/