Attribute changelog_file not having an effect

[msandrk]

Running python-semantic-release==9.7.1 as a part of a Gitlab CI/CD pipeline always creates the changelog file named CHANGELOG.md in the root of the repository, no matter what I specify in the changelog_file attribute of the pyproject.toml file.

As described in the documentation, by using the changelog_file attribute in the [tool.semantic_release.changelog] part of the pyproject.toml configuration file, one is suppose to be able to specify a name for the changelog file to be created by python-semantic-release.
My initial thought was to use this attribute to put the changelog file in a subdirectory. E. g. changelog_file = "./docs/CHANGELOG.md".
When this didn't work, out of curiosity I've tried to just change the name of the resulting changelog file and not the location. E.g. changelog_file = "REALLY_COOL_CHANGELOG.md". Still, changelog file that is created is simply named CHANGELOG.md which is also the default value.

I'm running python-semantic-release as a job in a GitLab CI/CD pipeline inside a Docker container based on Debian GNU/Linux 10 (buster).

python --version -> 3.11.4
pip --version -> 24.0
semantic-release --version -> 9.7.1

Same behavior happens regardless of using poetry or pip + requirements.txt

Configuration

[tool.semantic_release]
version_toml = ["pyproject.toml:tool.poetry.version"]
assets = []
commit_message = "{version}\n\nAutomatically generated by python-semantic-release"
commit_parser = "angular"
logging_use_named_masks = false
hvcs = "gitlab"
major_on_zero = true
tag_format = "v{version}"

[tool.semantic_release.branches.main]
match = "(main|master)"
prerelease_token = "rc"
prerelease = false
hvcs = "gitlab"

[tool.semantic_release.changelog]
template_dir = "templates"
changelog_file = "PRETTY_COOL_CHANGELOG.md"
exclude_commit_patterns = []

[tool.semantic_release.remote]
type = "gitlab"

[tool.semantic_release.remote.token]
env = "GROUP_GITLAB_TOKEN"

[tool.semantic_release.changelog.environment]
block_start_string = "{%"
block_end_string = "%}"
variable_start_string = "{{"
variable_end_string = "}}"
comment_start_string = "{#"
comment_end_string = "#}"
trim_blocks = false
lstrip_blocks = false
newline_sequence = "\n"
keep_trailing_newline = false
extensions = []
autoescape = true

Logs

semantic-release -vv version

[12:10:43] DEBUG    [semantic_release.cli.commands.main] DEBUG       main.py:105
                    main.main: logging level set to: DEBUG                      
           DEBUG    [git.util] DEBUG util.is_cygwin_git: Failed      util.py:439
                    checking if running in CYGWIN due to:                       
                    FileNotFoundError(2, 'No such file or                       
                    directory')                                                 
           DEBUG    [semantic_release.cli.commands.main] DEBUG       main.py:123
                    main.main: global cli options:                              
                    GlobalCommandLineOptions(noop=False,                        
                    verbosity=2, config_file='pyproject.toml',                  
                    strict=False)                                               
           INFO     [semantic_release.cli.util] INFO                  util.py:78
                    util.load_raw_config_file: Loading configuration            
                    from pyproject.toml                                         
           DEBUG    [semantic_release.cli.util] DEBUG                 util.py:81
                    util.load_raw_config_file: Trying to parse                  
                    configuration pyproject.toml in TOML format                 
           INFO     [semantic_release.cli.config] INFO             config.py:238
                    config.select_branch_options: Using group                   
                    'main' options, as '(main|master)' matches                  
                    'master'                                                    
           DEBUG    [semantic_release.hvcs.util] DEBUG                util.py:48
                    util.build_requests_session: setting up default             
                    session authentication                                      
           DEBUG    [semantic_release.changelog.template] DEBUG   template.py:55
                    template.environment: {'template_dir':                      
                    'templates', 'block_start_string': '{%',                    
                    'block_end_string': '%}',                                   
                    'variable_start_string': '{{',                              
                    'variable_end_string': '}}',                                
                    'comment_start_string': '{#',                               
                    'comment_end_string': '#}',                                 
                    'line_statement_prefix': None,                              
                    'line_comment_prefix': None, 'trim_blocks':                 
                    False, 'lstrip_blocks': False,                              
                    'newline_sequence': '\n',                                   
                    'keep_trailing_newline': False, 'extensions':               
                    (), 'autoescape': True, 'autoescape_value':                 
                    True}                                                       
           DEBUG    [semantic_release.version.translator] DEBUG translator.py:40
                    translator._invert_tag_format_to_re:                        
                    inverted tag_format 'v{version}' to                         
                    'v(?P<version>.*)'                                          
           DEBUG    [semantic_release.cli.masking_filter]   masking_filter.py:30
                    DEBUG masking_filter.add_mask_for:                          
                    Adding redact pattern                                       
                    'context.hvcs_client.token' to                              
                    _redact_patterns                                            
           DEBUG    [semantic_release.cli.masking_filter]   masking_filter.py:30
                    DEBUG masking_filter.add_mask_for:                          
                    Adding redact pattern                                       
                    'context.hvcs_client.token' to                              
                    _redact_patterns                                            
           DEBUG    [semantic_release.cli.commands.version] DEBUG  version.py:47
                    version.is_forced_prerelease: force_prerelease              
                    = False, force_level = None, prerelease =                   
                    False                                                       
           DEBUG    [semantic_release.version.version] DEBUG      version.py:121
                    version.parse: attempting to parse string                   
                    '0.1.0' as Version                                          
           DEBUG    [semantic_release.version.version] DEBUG      version.py:145
                    version.parse: version string 0.1.0 parsed as               
                    a non-prerelease                                            
           DEBUG    [semantic_release.version.version] DEBUG      version.py:148
                    version.parse: parsed build metadata '' from                
                    version string 0.1.0                                        
           DEBUG    [semantic_release.version.version] DEBUG      version.py:121
                    version.parse: attempting to parse string                   
                    '0.1.1' as Version                                          
           DEBUG    [semantic_release.version.version] DEBUG      version.py:145
                    version.parse: version string 0.1.1 parsed as               
                    a non-prerelease                                            
           DEBUG    [semantic_release.version.version] DEBUG      version.py:148
                    version.parse: parsed build metadata '' from                
                    version string 0.1.1                                        
           DEBUG    [semantic_release.version.version] DEBUG      version.py:121
                    version.parse: attempting to parse string                   
                    '0.1.2' as Version                                          
           DEBUG    [semantic_release.version.version] DEBUG      version.py:145
                    version.parse: version string 0.1.2 parsed as               
                    a non-prerelease                                            
           DEBUG    [semantic_release.version.version] DEBUG      version.py:148
                    version.parse: parsed build metadata '' from                
                    version string 0.1.2                                        
           DEBUG    [semantic_release.version.version] DEBUG      version.py:121
                    version.parse: attempting to parse string                   
                    '0.2.0' as Version                                          
           DEBUG    [semantic_release.version.version] DEBUG      version.py:145
                    version.parse: version string 0.2.0 parsed as               
                    a non-prerelease                                            
           DEBUG    [semantic_release.version.version] DEBUG      version.py:148
                    version.parse: parsed build metadata '' from                
                    version string 0.2.0                                        
           DEBUG    [semantic_release.version.version] DEBUG      version.py:121
                    version.parse: attempting to parse string                   
                    '0.3.0' as Version                                          
           DEBUG    [semantic_release.version.version] DEBUG      version.py:145
                    version.parse: version string 0.3.0 parsed as               
                    a non-prerelease                                            
           DEBUG    [semantic_release.version.version] DEBUG      version.py:148
                    version.parse: parsed build metadata '' from                
                    version string 0.3.0                                        
           INFO     [semantic_release.version.algorithm] INFO    algorithm.py:60
                    algorithm.tags_and_versions: found 5                        
                    previous tags                                               
           INFO     [semantic_release.version.algorithm] INFO   algorithm.py:255
                    algorithm.next_version: Found 5 full                        
                    releases (excluding prereleases)                            
           DEBUG    [semantic_release.version.version] DEBUG      version.py:121
                    version.parse: attempting to parse string                   
                    '0.0.0' as Version                                          
           DEBUG    [semantic_release.version.version] DEBUG      version.py:145
                    version.parse: version string 0.0.0 parsed as               
                    a non-prerelease                                            
           DEBUG    [semantic_release.version.version] DEBUG      version.py:148
                    version.parse: parsed build metadata '' from                
                    version string 0.0.0                                        
           INFO     [semantic_release.version.algorithm] INFO   algorithm.py:277
                    algorithm.next_version: The last full                       
                    release was 0.3.0, tagged as 'v0.3.0'                       
           DEBUG    [git.cmd] DEBUG cmd.execute: Popen(['git',        cmd.py:978
                    'merge-base', 'v0.3.0', 'master'],                          
                    cwd=/builds/username/test-cicd, stdin=None,            
                    shell=False, universal_newlines=False)                      
           DEBUG    [git.cmd] DEBUG cmd.execute: Popen(['git',        cmd.py:978
                    'cat-file', '--batch-check'],                               
                    cwd=/builds/username/test-cicd, stdin=<valid           
                    stream>, shell=False, universal_newlines=False)             
           DEBUG    [git.cmd] DEBUG cmd.execute: Popen(['git',        cmd.py:978
                    'cat-file', '--batch'],                                     
                    cwd=/builds/username/test-cicd, stdin=<valid           
                    stream>, shell=False, universal_newlines=False)             
           DEBUG    [semantic_release.version.algorithm] DEBUG   algorithm.py:89
                    algorithm.bfs: checking if tag 'v0.3.0'                     
                    (c5bc21de87f9da03f99d8[221](https://some-gitlab.company.com/username/test-cicd/-/jobs/825662#L221)a1433b75cc75602e)                  
                    matches commit                                              
                    c5bc21de87f9da03f99d8221a1433b75cc75602e                    
           INFO     [semantic_release.version.algorithm] INFO    algorithm.py:96
                    algorithm.bfs: found latest version in                      
                    branch history: '0.3.0' (c5bc21d)                           
           INFO     [semantic_release.version.algorithm] INFO   algorithm.py:115
                    algorithm._bfs_for_latest_version_in_histor                 
                    y: the latest version in this branch's                      
                    history is 0.3.0                                            
           INFO     [semantic_release.version.algorithm] INFO   algorithm.py:302
                    algorithm.next_version: The last full                       
                    version in this branch's history was 0.3.0                  
           DEBUG    [git.cmd] DEBUG cmd.execute: Popen(['git',        cmd.py:978
                    'rev-list', 'v0.3.0...', '--'],                             
                    cwd=/builds/username/test-cicd, stdin=None,            
                    shell=False, universal_newlines=False)                      
           DEBUG    [semantic_release.version.algorithm] DEBUG  algorithm.py:374
                    algorithm.next_version: parsed the                          
                    following distinct levels from the commits                  
                    since the last release: set()                               
           INFO     [semantic_release.version.algorithm] INFO   algorithm.py:380
                    algorithm.next_version: The type of the                     
                    next release release is: no_release                         
           INFO     [semantic_release.version.algorithm] INFO   algorithm.py:382
                    algorithm.next_version: No release will be                  
                    made                                                        
0.3.0
           DEBUG    [semantic_release.version.version] DEBUG      version.py:121
                    version.parse: attempting to parse string                   
                    '0.1.0' as Version                                          
[12:10:44] DEBUG    [semantic_release.version.version] DEBUG      version.py:145
                    version.parse: version string 0.1.0 parsed as               
                    a non-prerelease                                            
           DEBUG    [semantic_release.version.version] DEBUG      version.py:148
                    version.parse: parsed build metadata '' from                
                    version string 0.1.0                                        
           DEBUG    [semantic_release.version.version] DEBUG      version.py:121
                    version.parse: attempting to parse string                   
                    '0.1.1' as Version                                          
           DEBUG    [semantic_release.version.version] DEBUG      version.py:145
                    version.parse: version string 0.1.1 parsed as               
                    a non-prerelease                                            
           DEBUG    [semantic_release.version.version] DEBUG      version.py:148
                    version.parse: parsed build metadata '' from                
                    version string 0.1.1                                        
           DEBUG    [semantic_release.version.version] DEBUG      version.py:121
                    version.parse: attempting to parse string                   
                    '0.1.2' as Version                                          
           DEBUG    [semantic_release.version.version] DEBUG      version.py:145
                    version.parse: version string 0.1.2 parsed as               
                    a non-prerelease                                            
           DEBUG    [semantic_release.version.version] DEBUG      version.py:148
                    version.parse: parsed build metadata '' from                
                    version string 0.1.2                                        
           DEBUG    [semantic_release.version.version] DEBUG      version.py:121
                    version.parse: attempting to parse string                   
                    '0.2.0' as Version                                          
           DEBUG    [semantic_release.version.version] DEBUG      version.py:145
                    version.parse: version string 0.2.0 parsed as               
                    a non-prerelease                                            
           DEBUG    [semantic_release.version.version] DEBUG      version.py:148
                    version.parse: parsed build metadata '' from                
                    version string 0.2.0                                        
           DEBUG    [semantic_release.version.version] DEBUG      version.py:121
                    version.parse: attempting to parse string                   
                    '0.3.0' as Version                                          
           DEBUG    [semantic_release.version.version] DEBUG      version.py:145
                    version.parse: version string 0.3.0 parsed as               
                    a non-prerelease                                            
           DEBUG    [semantic_release.version.version] DEBUG      version.py:148
                    version.parse: parsed build metadata '' from                
                    version string 0.3.0                                        
           INFO     [semantic_release.version.algorithm] INFO    algorithm.py:60
                    algorithm.tags_and_versions: found 5                        
                    previous tags                                               
No release will be made, 0.3.0 has already been released!
           INFO     [semantic_release.cli.github_act github_actions_output.py:70
                    ions_output] INFO                                           
                    github_actions_output.write_if_p                            
                    ossible: not writing GitHub                                 
                    Actions output, as no file                                  
                    specified

Additionally, even though messages in the log above suggest that "No release will be made" the 0.3.0 release is indeed made as it should be in this demo case because previous version was 0.2.0 and feat commits were made in the meanwhile.

A custom template for the changelog file is used and the changelog created by the python-semantic-release is indeed based on that custom template, however it is not named correctly.

Obviously I've changed a few details in the presented pyproject.toml and log output because we are using python-semantic-release as a part of a private, company repository.

Am I doing something wrong or is this a bug?

[codejedi365]

I'm sorry for the confusion you are experiencing.

Initially, if you are using the custom template directory (and the directory exists) then the changelog_file config option is unused. If you change the name of your template to a different name it should replicate the name from the template directory.

Additionally if you want it to be in the docs folder, make a docs folder in the template directory and place your changelog template into that directory. The folder structure will be transplanted into your project structure after stripping off the config defined template directory

[msandrk]

Ok, now everything makes sense.

Thank you very much! :)