publish_tools

Description:

publish tools

publish_tools #

This package provides a set of Grinder tasks that make it easy to release a Dart and Flutter packages.

Table of contents #

Getting started

Requirements
pubspec.yaml setup
publish_tools.yaml setup
README.md/CHANGELOG.md templates


Grinder Tasks
In the next major release

Getting started #
Requirements #
In able to use the GitHub publishing features of this package your development setup must meet the following requirements:

git must be available in your command path (most people reading this will have this requirement met, if not see - Installing Git)
you have a GitHub account and have setup a personal access token (see the documentation - Creating a personal access token)
A fine grain token requires the following permissions:

Read and write - Administration - for the Homebrew tap repository creation
Read and write - Contents - to update repository content and crete the release for the tap
Read-only - Metadata - mandatory for all fine-grained personal access tokens



Make sure that you .gitignore your publish_tools.yaml file to prevent publishing your token to GitHub
pubspec.yaml setup #
In your pubspec.yaml the following to the dev_dependencies section:
dev_dependencies:
...
grinder: ^0.9.5
publish_tools: ^1.0.0+5
copied to clipboard
Optionally, provide a non-default path for your configuration .yaml file: (remember to .gitignore it)
publish_tools: tool/config.yaml
copied to clipboard
publish_tools.yaml setup #
Create a folder named tool (which will already exist if you use the grinder package). In this folder create you publish_tools configuration file.
## this is a minimal config, several fields will be assigned default values

## If the github key is present, it will override the default (grab values from .git folder)
# github:
# repoUser: [your github user]
# repoName: [defaults to 'name' from pubspec.yaml]

## If the templates key is present, defaults are overridden. Below matches the default config.
# templates:
# - name: README.md
# type: overwrite
# - name: CHANGELOG.md
# type: prepend

commit: 'sample commit message'
copied to clipboard
Create
import 'package:publish_tools/publish_tools.dart';

main(args) async {
PublishTools.addAllTasks();

grind(args);
}

@DefaultTask('Just keeping it real')
@Depends('pt-commit')
build() {
log('building...');
}
copied to clipboard
README.md/CHANGELOG.md templates #
publish_tools can make it easier for you to keep your README.md and CHANGELOG.md file up to date. To do this it uses mustache templates to dynamically re-create your README and CHANGELOG when you run the appropriate grinder task. To configure your project to make use of this functionality, you need to have a README.md and CHANGELOG.md mustache template available to the build tool.
The quickest and simplest way to get your templates in place is to copy your existing README.md and CHANGELOG.md into the tool folder. Now you can update these files with dynamic fields that will be replaced when the pt-markdown grinder task is run.
For instance, in this README file in the pubspec.yaml setup section above, there are instructions and an example of how to update your pubspec.yaml to use this tool. The publish_tools version in the README is set dynamically with a variable. Here is the section of markup for the same section in the tool/README.md mustache template:
```yml
dev_dependencies:
...
grinder: ^0.9.2
publish_tools: ^{{ pubspec.version }}
```
copied to clipboard
The value for {{ pubspec.version }} is filled in automatically by the pt-markdown grinder task.
Or for the CHANGELOG.md the following template might be used:
# Changelog

## {{ pubspec.version }}

{{ changes }}
copied to clipboard
By default the README.md file is overwritten each time the pt-markdown task runs. However thee CHANGELOG.md file is prepended by default. This means that the supplied template will be added to the start of the existing CHANGELOG.md file.
Other available values that can be used dynamically are:



object
attribute
description




pubspec

Information contained within the project pubspec.yaml file.



name
Project name.



version
Project version.



homepage
URL pointing to the package’s homepage (or source code repository).



documentation
URL pointing to documentation for the package.



description
Project short description.



publishTo
Specifies where to publish a package.


github

Values from the publish_tools config file related to GitHub.



repoUser
The GitHub username associated with this project.



repoName
The GitHub repository name for this project.


homebrew

Values from the publish_tools config file related to HomeBrew.



className
The name of the class created for the HomeBrew ruby file for the tap repository that will be created and published to GutHub



description
The description given in the ruby tap repository



homePage
The description given in the ruby tap repository. By default this is the same as pubspec.homepage.



binSrc
The file name of the source code for the command line binary of the project. The file is expected to be found in the homebrew.binFolder and by default the expected file name is [pubspec.name].dart.



executableName
The name of the compiled executable for the command line binary to be used by end-users, defaults to pubspec.name.



binFolder
The folder that contains the binary source for the command line executeable, defaults to bin


meta_path

The location to write the meta.dart file that is used to supply pubspec info to the cli binary executable, defaults to lib/meta.dart.


commit

The commit message supplied in the publish_tools config file.


changes

The changes (for the CHANGELOG.md) supplied in the publish_tools config file.



Grinder Tasks #
Here is the list of grinder tasks available in this package:



Task name
Description




pt-analyze
Analyze Dart code in a directory - dart analyze .


pt-format
Idiomatically format Dart source code - dart format .


pt-doc
Generate API documentation for Dart projects - dart doc .


pt-test
Generate API documentation for Dart projects - dart test .


pt-meta
Creates a file meta.dart in the folder specified by the config (defaults to src/util/), this file contains a JSON representation of the pubspec.yaml file, giving access to that information to cli programs.


pt-markdown
Processes any markdown templates references in the config. Usually the README.md and the CHANGELOG.md, the templates can use mustache syntax to access data from the ptConfig object.


pt-commit
Commit the project to github [git add ., git commit {{ ptConfig.commit }}, git pull --tags, git tag v${pubSpec.version}, git push --tags, git push]. Only if {{ pubSpec.version }} has changed, will a new tag be created.


pt-release
Create a Release for the current project in GitHub


pt-homebrew
Create a HomeBrew tap for the command line executable for this project


pt-clean
Remove build and homebrew repository folders created by this tool.


pt-publish
Publish the current package to pub.dev.



In the next major release #

Chocolatey support
NPM support