Как автоматически обновлять содержимое файла README?

Question

Имеется README.md файл содержащий различные текстовые заменители, которые преобразуются в значения файла pom.xml. Файл располагается по пути {project.basedir}/doc/README.md и при сборке проекта обрабатывается плагином maven-resources-plugin, который преобразует текстовые заполнители и копирует его в корневую директорию проекта, а на следующем этапе в целевую директорию (чтоб также находился в корне JAR):

Пример содержимого файла README.md:

# ${project.name}

${project.description}

[[_TOC_]]

## Used Maven Dependencies

- [JUnit](https://junit.org/junit5/docs/${junit}/api/) v.${junit}
- [SELF4J](https://www.javadoc.io/static/org.slf4j/slf4j-api/${slf4j}/index.html) v.${slf4j}
- ...

## Build

Compiled and built at ${timestamp} with:

- Java: ${java.version}
- Maven: ${maven.version}

```xml
<dependency>
    <groupId>${project.groupId}</groupId>
    <artifactId>${project.artifactId}</artifactId>
    <version>${project.version}</version>
</dependency>
```

В файле pom.xml обработка настраивается так:

<?xml version="1.0" encoding="UTF-8"?>
<project ...>
  <!-- ... -->
  <properties>
    <timestamp>${maven.build.timestamp}</timestamp>
    <maven.build.timestamp.format>yyyy-MM-dd HH:mm</maven.build.timestamp.format>
    <!-- ... -->
  </properties>
  <!-- ... -->
  <build>
    <!-- ... -->
    <plugins>
      <plugin>
        <artifactId>maven-resources-plugin</artifactId>
        <version>3.1.0</version>
        <executions>
          <execution>
            <id>replace-placeholders-in-readme</id>
            <phase>validate</phase>
            <goals>
              <goal>copy-resources</goal>
            </goals>
            <configuration>
              <outputDirectory>${project.basedir}</outputDirectory>
              <resources>
                <resource>
                  <directory>${project.basedir}/doc</directory>
                  <includes>
                    <include>README.md</include>
                  </includes>
                  <filtering>true</filtering>
                </resource>
              </resources>
              <encoding>UTF-8</encoding>
            </configuration>
          </execution>
          <execution>
            <id>copy-readme-to-output</id>
            <phase>compile</phase>
            <goals>
              <goal>copy-resources</goal>
            </goals>
            <configuration>
              <outputDirectory>${project.build.outputDirectory}</outputDirectory>
              <resources>
                <resource>
                  <directory>${project.basedir}</directory>
                  <includes>
                    <include>README.md</include>
                  </includes>
                </resource>
              </resources>
              <encoding>UTF-8</encoding>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>

Проблема в том, что для выполнения всего этого преобразования необходимо на локальной машине выполнить сборку через maven (например, mvn verify), т.к. в противном случае изменённый файл README.md будет присутствовать в сборке/JAR-файле, но не в репозитории. К примеру, в pom.xml изменилась версия зависимости, а в файле README.md используется старая версия/ссылка.

Вопрос: можно ли каким-либо образом настроить автоматическое генерирование файла README.md хоть на локальной машине, хоть на стороне GitLab (прописать в gitlab-ci.yml)? В идеале хотелось бы генерировать файл при каждой фиксации и автоматически его "push'ить" в репозиторий.

Ссылки по теме

maven-resources-plugin

Answer 1

Поскольку файл меняется на этапе компиляции, а тесты выполняются после, то тест будет проверять изменения. Можно воспользоваться средствами git git diff --exit-code README.md , выяснить, вносились изменения в файл, и если они есть, то бросать ошибку и писать соответствующее сообщение.

Пример:

public static void main(String[] args) throws IOException {

    Runtime rt = Runtime.getRuntime();
    String[] commands = {"git", "diff", "--exit-code", "README.md"};
    Process proc = rt.exec(commands);

    BufferedReader stdInput = new BufferedReader(new InputStreamReader(proc.getInputStream()));
    BufferedReader stdError = new BufferedReader(new InputStreamReader(proc.getErrorStream()));

    String s = null;
    while ((s = stdInput.readLine()) != null) {
        if (!s.isEmpty()){
            throw new RuntimeException("README.md was changed, please commit changes!");
        }
    }

    while ((s = stdError.readLine()) != null) {
        if (!s.isEmpty()){
            throw new RuntimeException("git required or unknown error");
        }
    }
}

Аналогичную проверку можно написать в скрипте отдельным шагом для CI.

БЛОГ НА HUSL

Как автоматически обновлять содержимое файла README?

Ссылки по теме

Ответы (1 шт):