Recommended files
A module to find and identify a set of recommended files, like README, CONTRIBUTING, etc.
It can query GitHub or GitLab projects, and tries to follow the recommendations of the Eclipse Project Handbook [1] and the former analyser [2].
[1] https://www.eclipse.org/projects/handbook/ [2] https://www.eclipse.org/projects/tools/documentation.php
It looks for a set of files for each category of best practices, namely:
- Readme -
readmeorreadme.md - Conduct -
code_of_conduct.md - Contributing -
contributingorcontributing.md - License -
license
It only looks for files at the root of the repository. Search is case-insensitive.
files_conduct = {'code_of_conduct.md'}
module-attribute
The list of file names considered as codes of conduct.
files_contributing = {'contributing', 'contributing.md'}
module-attribute
The list of file names considered as contributing guides.
files_license = {'license'}
module-attribute
The list of file names considered as license texts.
files_notice = {}
module-attribute
The list of file names considered as notices.
files_readme = {'readme', 'readme.md'}
module-attribute
The list of file names considered as readme's.
files_security = {}
module-attribute
The list of file names considered for security information.
analyse_project(project_id, credentials=None, verbose=False)
Generic entrypoint to analyse a project. This function will identify the project repositories and their type (github/gitlab) and execute the corresponding functions.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
project_id
|
str
|
Project ID of the Eclipse project to analyse, e.g. |
required |
credentials
|
Optional[dict]
|
A dict contining GitHub and GitLab token to use to connect to GitHub. |
None
|
verbose
|
Optional[bool]
|
Should we print more information on stdout? |
False
|
find_file_in_list(files_repo, files_lookup, verbose=False)
Go through a list of regular expressions from files_lookup, matching strings from files_repo,
and stops and returns the first corresponding occurrence.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
files_repo
|
str
|
An array of files to search through, and match to the regular expressions. |
required |
files_lookup
|
str
|
An array of regular expressions (either string or raw string) to match against the list of files. |
required |
verbose
|
Optional[bool]
|
Should we print more information on stdout? |
False
|
gh_analyse(organisation, credentials=None, verbose=False)
Analyse one or more GH repositories, looking for all interesting files in its content.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
organisation
|
str
|
GitHub organisation to analyse. |
required |
credentials
|
Optional[dict]
|
A dict contining GitHub and GitLab token to use to connect to GitHub. |
None
|
verbose
|
Optional[bool]
|
Should we print more information on stdout? |
False
|
gl_analyse(organisation, credentials=None, verbose=False)
Analyse all repositories from a single organisation, looking for all interesting files.
This function in turns calls everything needed to execute the full analysis, from GL authentication and initialisation to the actual query.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
organisation
|
str
|
An organisation to analyse.SSS |
required |
credentials
|
Optional[dict]
|
A dict containing GitHub and GitLab token to use to connect to GitHub. |
None
|
verbose
|
Optional[bool]
|
Should we print more information on stdout? |
False
|