Merge branch 'master' into bugfix/fix-for-user-fields-on-first-revision

docs/CODE_OF_CONDUCT.md

@@ -34,7 +34,7 @@ This Code of Conduct applies both within project spaces and in public spaces whe
 
 ## Enforcement
 
-Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at [email protected]. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at <mailto:[email protected]>. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
 
 Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
 

docs/config.md

@@ -82,8 +82,8 @@ Name-value pairs of work item types to map in the migration.
 |**for**|False|string|Types of work items this field should be migrated to, i.e. Bug, Task, Product backlog item in a comma-delimiter list. Default = "All".  When adding for ensure that a TypeMap.target is specified, specifying a TypeMap.source will cause fields to not be merged.|
 |**not-for**|False|string|Negation of above, i.e this field is for a Bug only and nothing else.  When adding for ensure that a TypeMap.target is specified, specifying a TypeMap.source will cause fields to not be merged.|
 |**type**|False|string|Data type, i.e string, int, double. Default = string|
-|**mapper**|False|string|Mapper function used for value translation. See section below for a quick summary of the available mappers.|
-|**mapping**|False|json|List of **values** to map to and from in the migration.|
+|**mapper**|False|string|Mapper function used for value translation. See the **Mappers** section below for a quick summary of the available mappers.|
+|**mapping**|False|json|List of **key value pairs** to map to and from in the migration. Use this instead of the **mapper** property if you need a simple key-value mapping.|
 
 ## Value properties
 
@@ -105,7 +105,7 @@ Name-value pairs of repositories to map in the migration.
 
 ## Mappers
 
-Currently the tool has a rather naive implementation for mapping certain constructs, this is something we would like to improve in the future. But for now it is what it is and the table below is intended as a summary/explanation.
+Mappers are functions used byt he **Jira Exporter** for transforming the data in the Jira issue fields. The table below is as a summary and explanation of the different mappers available.
 
 **Note**: the source code for the mapping logic is here: <https://github.com/solidify/jira-azuredevops-migrator/blob/master/src/WorkItemMigrator/JiraExport/JiraMapper.cs>
 

docs/faq.md

@@ -21,7 +21,7 @@ Example:
 - Try different combinations of your jira user/api credentials. The functionality here could depend on wether you are using Jira Cloud or Jira Server, as well as wether you have set your user's email as public in the user profile in Jira Cloud, and jira might not be accepting certain credentials. Try all combinations of the following:
   - username: **email**
   - username: **Jira Username**
-  - username: **accountId** (navigate to your user profile and find the accountId in the URL, for example: https://solidifydemo.atlassian.net/jira/people/ **6038bfcc25b84ea0696240d4**
+  - username: **accountId** (navigate to your user profile and find the accountId in the URL, for example: <https://solidifydemo.atlassian.net/jira/people/>**6038bfcc25b84ea0696240d4**
   - password: **user password** (same as login)
   - password: **API token**
 
@@ -64,15 +64,27 @@ Example:
 
 - User mapping differs between Jira Cloud and Jira Server. To migrate users and assign the new work items in Azure DevOps to the same user as the original task had in Jira, we need to add a text file in the root that would look something like this:
 
-- When using Jira Cloud then firstly make sure in the config the '"using-jira-cloud": true' is set. The user mapping file should have accountId/email value pairs. To use email value pairs the users email should be set to public in the user profile in Jira Cloud, otherwise the tool cant get the email and will use accountId instead for mapping.
-
     ```txt
     [email protected][email protected]
     [email protected][email protected]
     [email protected][email protected]
     ```
 
-    or
+- When using Jira Cloud then firstly make sure in the config the '"using-jira-cloud": true' is set. The user mapping file should have accountId/email value pairs. To use email value pairs the users email should be set to public in the user profile in Jira Cloud, otherwise the tool cant get the email and will use accountId instead for mapping.
+
+- It can happen that the **JiraExporter** cannot find you users' email addresses. This will happen if e.g. your user has chosen not to make their email address public. You will then receive the following warning when running the **jira-expoprt.exe**:
+
+    ```
+    [W][01:57:30] Email is not public for user '630ddc7d316bbc88c1234e3b' in Jira, using usernameOrAccountId '630ddc7d316bbc88c1234e3b' for mapping.
+    ```
+
+    If you receive such a warning, you will need to map the users' IDs instead, just like you would with the emails. You will need to include the following line in your `users.txt`:
+
+    ```
+    [email protected]
+    ```
+
+    The correct format of the `users.txt`-file would then be:
 
     ```txt
     [email protected]

docs/journalfile.md

@@ -23,4 +23,4 @@ SCRUM-18;9192;2
 SCRUM-19;9193;1
 SCRUM-19;9193;2
 SCRUM-20;9194;1
-```
+```

docs/overview.md

@@ -6,11 +6,11 @@ The migration process is done in two phases, first data is exported from Jira to
 
 The second step imports the data files to work items in Azure DevOps/TFS.
 
-The key capabilities of the tool includes:
+The key capabilities of the tool include:
 
 - Jira items are exported based on JQL queries.
 - Users can be translated during migration in order to maintain proper history.
-- Field mapping is provided to map fields from the source to target account based on configuration file.
+- Field mapping is provided to map fields from the source to target account based on a configuration file.
 - State mapping between Jira and Azure DevOps states.
 - History from Jira is maintained.
 - Dates such as created or changed date are maintained.