twitter / repo-scaffolding

Tools for creating repos based on open source standards and best practices

repo-scaffolding

Scaffolding tools for creating and maintaining projects based on Twitter Open Source standards and best practices. The project has 3 parts -

1. Cookiecutter template to generate Twitter OSS policy files e.g. LICENSE, CONTRIBUTING, etc.
2. Script to add License headers to all source files in a project
3. Lint a repository for common missing files (repolinter)

---

1. Cookiecutter template to generate OSS policy files

A cookiecutter template to generate necessary files for a Twitter Open Source project.

Requirements

Install cookiecutter command line: pip install cookiecutter

---

pip is the package manager for Python.

Note: cookiecutter can be installed with both pip and pip3.

Usage

Run cookiecutter against this repository.

cookiecutter https://github.com/twitter/repo-scaffolding

or

cookiecutter gh:twitter/repo-scaffolding

or

You can also run it locally after cloning this repository:

cookiecutter /path/to/directory/

See documentation for more usage instructions.

Inputs

See cookiecutter.json for all the variables required as input. Here is the list of places they are used

• author_full_name: 1 time in README.md in the Authors section.
• author_email: 1 time in README.md in the Authors section
• project_slug: 1 time in README.md and also for the name of the parent directory
• github_repo_url: 2 times in README.md and 4 times in CONTRIBUTING.md for the GitHub repo links
• short_description: 1 time in README.md
• project_homepage: 1 time in README.md
• documentation_homepage: 1 time in README.md
• mailing_list: 1 time in README.md
• release_year: 1 time in LICENSE and 1 time in README.md

Notes

• Make sure to update the TODO sections in README.md and CONTRIBUTING.md after generating the files

2. License Headers

All source files must have a license header at the top. If you need to add headers to a lot of files, we recommend using the google/addlicense tool.

Installation

Download the latest release for your operating system, and place the binary someone in your shell path (like /usr/local/bin/). Alternately, follow the instructions for running with Docker.

Usage

First, check to see which files addlicense would add headers to:

$ cd <path_to_source_dir>
$ addlicense -check .

If that looks right, add the appropriate Twitter headers:

$ addlicense -c "Twitter, Inc." -l "Apache-2.0" -s=only .

If you have third-party source in a vendor or node_modules directory, you can ignore those with the -ignore flag to addlicense.

3. Linting (repolinter)

Lint all the necessary files in the project. - Project Homepage

• To run against a directory, use npx repolinter /my/code/dir
• To run against a git repository, use the --git option: npx repolinter --git https://my.git.code/awesome
• Note, if you are running a version of npm < 5.2.0, run npm install npx first.

---

Authors

• TwitterOSS <opensource [at] twitter [dot] com>

Follow @TwitterOSS on Twitter for updates.

repo-scaffolding's Issues

System Information Leak：Internal

repo-scaffolding/add_license_headers.py

Line 538 in 2586778

print("2. Review the detailed log file - " + color.BOLD + os.getcwd() + "/" + LOG_FILENAME, color.END)

An internal information leak occurs when system data or debugging information is sent to a local file, console, or screen via printing or logging.
It is recommended to use concise and ambiguous information to prompt the user

NameError in add_license_headers script

I'm hitting a NameError exception when trying to run the add_license_headers script (see below)

Expected behavior

Script adds license headers

Actual behavior

Script fails without adding headers

Steps to reproduce the behavior

[repo-scaffolding (master)]$ python setup.py install
[twemoji-parser (master)]$ add_license_headers ./src
('Path detected :', '\x1b[1m/Users/ndowns/workspace/twemoji-parser/src\x1b[0m')
('Branch detected -', u'\x1b[1mmaster', '\x1b[0m', '\n')
* Please make sure that the source directory is tracked by git.
* Create a new branch before proceeding ahead.
* Make sure you do not have any uncommitted changes in your repository.
It will later enable you to run 'git checkout -- .' and revert all the changes made by this script.
Proceed ahead? (Don't worry, this won't make changes yet) [y/N] y
Traceback (most recent call last):
  File "/usr/local/bin/add_license_headers", line 9, in <module>
    load_entry_point('add-license-headers==0.1', 'console_scripts', 'add_license_headers')()
  File "build/bdist.macosx-10.13-intel/egg/add_license_headers.py", line 518, in entry
  File "build/bdist.macosx-10.13-intel/egg/add_license_headers.py", line 325, in query_yes_no
  File "<string>", line 1, in <module>
NameError: name 'y' is not defined

[Feature] travis.yaml/circleci.yaml

Community members have requested that we add a feature to generate travis.yml (or circleci.yaml) file with our cookiecutter templates.

Expected behavior

After answering a series of questions, the user is presented with a populated travis or circleci config.

CircleCI: https://circleci.com/docs/2.0/sample-config/
Travis: https://docs.travis-ci.com/user/tutorial/

Actual behavior

There are no example CI configs shipped.

Steps to reproduce the behavior

Missing feature, no repro needed ;)