Micro-Change Miner

This is the repository for Micro-change Miner.

Micro-changes are a set of code change operations described in natural language, designed to bridge the cognitive divide by translating the textual diffs into more understandable natural-language described operations

---

📋 Table of Contents

• Micro-Change Miner
  • 📋 Table of Contents
  • 📦 Quickstart with make
  • 🧰 Prerequisites
    • 1. git-stein
    • 2. RefactoringMiner
    • 3. Gradle
  • 🔧 Build
  • 🛠️ How to Mine Micro-Changes from a Repository (Step-by-Step)
    • Step 1. Convert the target git repository to method-level repository
    • Step 2. Get commit-map
    • Step 3. Mine refactorings
    • Step 4. Mine micro-changes
  • 🧩 How to Define Your Own Micro-Change Types
    • 1. Implement the micro-change in package org.mashirocl.microchange
    • 2. Register your own micro-change for mining in org.mashirocl.command.MineCommand#loadMicroChanges()
  • 📚 Complete Micro-Change Catalog
  • 📄 Publications

---

📦 Quickstart with make

If you're using macOS or Linux and have make installed, you can skip manual setup. Just run:

$ make example-analysis

This will:

• Clone and build required tools (git-stein, RefactoringMiner)
• Set up directories
• Mine micro-changes from an example repository mbassador

---

If you prefer to install things manually, follow the steps below instead of using make

🧰 Prerequisites

Install the following tools before using Micro-Change Miner

1. git-stein

Used to convert Git repositories into method-level history.

• git-stein: Convert Git repository to method-level

$ git clone https://github.com/sh5i/git-stein.git
$ cd git-stein
$ ./gradlew executableJar

2. RefactoringMiner

We use the RefactoringMiner, which is the state of the art refactoring mining tool, to capture refactorings.

• Note that in the paper, we extend the RefactoringMiner3.0.4 by considering the refactoring affected elements' locations

3. Gradle

Install via Homebrew:

• gradle

$ brew install gradle

---

🔧 Build

Clone and build the project:

$ git clone git@github.com:MashiroCl/MicroChangeMiner.git
$ cd MicroChangeMiner
$ ./gradlew shadowJar

---

🛠️ How to Mine Micro-Changes from a Repository (Step-by-Step)

Step 1. Convert the target git repository to method-level repository

$ java -jar <git-stein_path/build/libs/git-stein.jar> <target_repo_path> -o <output_repo_path> @historage-jdt --no-original --no-classes --no-fields --parsable --mapping 

Step 2. Get commit-map

Obtain a map from a method-level repository whose key is the original repository sha1, value is the corresponding method-level repository sha1, i.e. <original_sha1:method-level_sha1>

$ java -jar build/libs/miner-1.0-SNAPSHOT-all.jar commitMap -p <method_level_repo_path/.git> -o <output_jsonfile.json>

Step 3. Mine refactorings

$ java -jar build/libs/miner-1.0-SNAPSHOT-all.jar refmine <RefactoringMiner_path>  <original_repo_path> <output_dir> >./runLog/<repo_name>_rm.log

Step 4. Mine micro-changes

$ java -jar  build/libs/miner-1.0-SNAPSHOT-all.jar mine <method_level_repo_path/.git> <output_json_path.json> --csv <output_csv_path.csv> --map <commit_map_path> --refactoring <mined_refactoring_directory> --original <original_repo_path/.git> --notCoveredPath <output_path_for_uncovered> >runLog/<repo_name>.log 

Example for mbassador:

$ java -jar  build/libs/miner-1.0-SNAPSHOT-all.jar mine ./method_level/mbassador/.git ./mined/mbassador.json --csv ./mined/mbassador.csv --map ./commitMap/mbassador.json --refactoring ./minedRefactoring/mbassador --original ./OSS/mbassador/.git --notCoveredPath ./notCovered/mbassador.json >runLog/mbassador.log

---

🧩 How to Define Your Own Micro-Change Types

1. Implement the micro-change in package org.mashirocl.microchange

public class YourMicroChange implements MicroChangePattern{
    @Override
    public boolean matchConditionGumTree(Action action, Map<Tree, Tree> mappings) {
      // Implement the match strategy here 
      // if you need the actions for all, implement the same name method below
        return false;
    }

    @Override
    public boolean matchConditionGumTree(Action action, Map<Tree, Tree> mappings, Map<Tree, List<Action>> nodeActions) {
      // Implement the match strategy here
        return false;
    }

    @Override
    public SrcDstRange getSrcDstRange(Action action, Map<Tree, Tree> mappings, Map<Tree, List<Action>> nodeActions, EditScriptStorer editScriptStorer) {
        // get the line range of this micro-change
        SrcDstRange srcDstRange = new SrcDstRange();
        // left side range

        // right side range

        return srcDstRange;
    }
}

2. Register your own micro-change for mining in org.mashirocl.command.MineCommand#loadMicroChanges()

    public static void loadMicroChanges(PatternMatcher patternMatcherGumTree) {
        patternMatcherGumTree.addMicroChange(new AddConjunctOrDisjunct());
        ...
        patternMatcherGumTree.addMicroChange(new YourMicroChange());

    }

---

📚 Complete Micro-Change Catalog

You can refer to the complete catalog of micro-change in Catalog.

---

📄 Publications

The following article includes the details of the micro-changes and the miner. We encourage contributions to the micro-changes or the miner.

Lei Chen, Michele Lanza, Shinpei Hayashi: ''Understanding Code Change with Micro-Changes''. In Proceedings of the 40th IEEE International Conference on Software Maintenance and Evolution (ICSME 2024). Flagstaff, AZ, USA, oct, 2024.

📖 Read on arXiv

@inproceedings{chen2024understanding,
  title={Understanding Code Change with Micro-Changes},
  author={Chen, Lei and Lanza, Michele and Hayashi, Shinpei},
  booktitle={Proceedings of the 40th International Conference on Software Maintenance and Evolution },
  pages={363--374},
  year={2024},
  keywords = {Software maintenance;Codes;Natural languages;Focusing;Detectors;Programming;Cognitive science;Logic},
  doi = {10.1109/ICSME58944.2024.00041},
  url = {https://doi.ieeecomputersociety.org/10.1109/ICSME58944.2024.00041},
  organization={IEEE}
}