1

Имеется 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'ить" в репозиторий.


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

4
  • Чем обоснован автоматический push в репозиторий? Может поступить от обратного: написать тест, который сравнит сгенерированное значение с сохраненным значением? И если упадет тест (во время прогона ci или локально), то разработчик увидит и обязательно закоммитит изменения. Необязательно тест, а отдельный скрипт, который сделает такую проверку на шаге post-compile к примеру. Commented 4 окт. 2022 в 15:54
  • вторая мысль посетила (еще не пользовался), сделать хук для git , можно выполнить отдельный скрипт перед коммитом pre-commit Commented 4 окт. 2022 в 15:59
  • @MrFylypenko "... написать тест, который сравнит сгенерированное значение с сохраненным значением?" - ну как бы в этом и вопрос. На счёт автоматического push'а, то представлял себе, что возможно сравнить два файла: который генерируется и находится в результирующей сборке с располагающимся в репозитории. Если не идентичны, то автоматически заpush'ить. Судя по тому, что не нашёл такой информации в нете, то видится мне, что это костыль и придётся просто в ручном режиме собирать локально сборку с Maven для обновления файла.
    – XelaNimed
    Commented 4 окт. 2022 в 18:33
  • С автоматическим push будет очень трудно жить, возникнет неуправляемый Dependency hell, на habr есть много статей как этого избежать. Это зависит от процессов которые используете в команде. Если вы единственный разработчик и одна ветка в репозитории, то автоматический push может существовать. Commented 5 окт. 2022 в 10:30

1 ответ 1

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.

3
  • Спасибо за Ваш ответ, но не понимаю каким образом выполнять этот код на этапе тестов и реализовать это на стороне GitLab сервера. Ну и конечно хотелось бы не доводить до выбрасывания ошибок.
    – XelaNimed
    Commented 7 окт. 2022 в 8:23
  • Создать @Test public void checkReadme () { ... } в каталоге тестов и добавить в него содержимое из main ответа. При выполнении mvn test этот тест будет выполнен. Про Ваши процессы разработки и настройку CI не знаю, можно настроить отдельный шаг для выполнения всех тестов или одного конкретного теста. Если выполняется в CI mvn package без параметра skipTests, то тесты должны выполняться. Commented 7 окт. 2022 в 9:15
  • Ну да... Чего то я затупил с тестами... Пятница и мысли уже не там где нужно... Большое спасибо : )
    – XelaNimed
    Commented 7 окт. 2022 в 10:58

Ваш ответ

Нажимая «Отправить ответ», вы соглашаетесь с условиями пользования и подтверждаете, что прочитали политику конфиденциальности.

Всё ещё ищете ответ? Посмотрите другие вопросы с метками или задайте свой вопрос.