Skip to content

Commit

Permalink
[DOC] Add documentation (#26)
Browse files Browse the repository at this point in the history 
* add badges, this closes #23

* document exporting CONDA_BLD_PATH, this closes #19

* add docs for versioning, this closes #21

* add documentation to differences to fastrelease, this closes #20

* add docs to compatibility with nbdev, this closes #24
  • Loading branch information
@PabloRMira
PabloRMira authored Jan 24, 2021
1 parent 6c2d354 commit 87a37fd
Show file tree
Hide file tree
Showing 3 changed files with 178 additions and 1 deletion.
52 changes: 52 additions & 0 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,10 @@
> Automate your GitHub, pypi and conda releases

[![PyPI](https://img.shields.io/pypi/v/easyrelease?color=yellow&label=pypi%20version)](https://pypi.org/project/easyrelease/#description)
[![conda](https://anaconda.org/pablormira/easyrelease/badges/version.svg)](https://anaconda.org/pablormira/easyrelease)
[![plattform](https://anaconda.org/pablormira/easyrelease/badges/platforms.svg)](https://anaconda.org/pablormira/easyrelease)

## How to install

Via pip
Expand Down Expand Up @@ -82,6 +86,17 @@ username = Your Anaconda username
password = Your Anaconda password
```

#### CONDA_BLD_PATH

> Only for Linux users and only in case of problems
In case of problems concerning permission errors building your package via `build-conda-package` you may need to add the following line to your `~/.bashrc`

```bash
export CONDA_BLD_PATH=/tmp/conda-bld
```


### Getting started

#### For applications
Expand All @@ -93,6 +108,15 @@ Only once:
2. Edit your in the previous step generated file `settings.ini`
3. Edit your in the previous step generated file `.gh-release-config.yaml`

`.gh-release-config.yaml` sets the title and keyword that will be used to assign your commits to a certain section in your GitHub release notes and changelog. So if for example you want all commits to be in your release notes without keyword matching, you could modify `.gh-release-config.yaml` as

```yaml
gh_categories:
- title: "### Commits:"
keyword: ""
```
Each time you want to make a GitHub release:
1. Run `gh-release` to make a GitHub release
Expand All @@ -117,3 +141,31 @@ Each time you want to release / publish your package:
* (Optionally recommended): Check your meta.yaml
5. Run `build-conda-package` to build your conda package
7. Run `upload-conda-package` to publish your conda package

## Versioning

We version our package via [semantic versioning](https://semver.org), i.e.,

* We use three digits separated by points x1.x2.x3, e.g. 0.5.1
* We increase x1 (the major version) if we introduce breaking changes
* Exception: Versions with 0 at the beginning (e.g. 0.5.1) mean that the package is not stable yet and therefore every new feature could be a breaking change
* We increase x2 (the minor version) if we introduce a new feature
* We increase x3 (the patch version) if we fix a bug

New documentation, refactoring / maintenance of code and admin tasks do not change the versions.

You can follow the changes introduced by each version in our [CHANGELOG](https://github.com/PabloRMira/easyrelease/blob/main/CHANGELOG.md)

## Differences to [fastrelease](https://github.com/fastai/fastrelease)

This package was inspired by the [fastrelease](https://github.com/fastai/fastrelease) package but it differs from it in the way it generates the release notes.

`easyrelease` generates the release notes out of the commit messages whereas `fastrelease` generates the release notes out of GitHub issues.

This package was also motivated by the fact that `fastrelease` did not work for me out of the box in my first attempt and I really liked the idea of automating releases and package publishing.

## Compatibility with [nbdev](https://github.com/fastai/nbdev)

This package was developed and is compatible with the [nbdev](https://github.com/fastai/nbdev) framework but it also works for ordinary project development without notebooks.

In the case you want to develop your project with `nbdev` you need to first initialize your project via `nbdev` and afterwards run `easyrelease-init`. This is because the `settings.ini` we initialize for your project is a proper / strict subset of the `settings.ini` from `nbdev`
54 changes: 54 additions & 0 deletions docs/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,15 @@
</div>
{% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p><a href="https://pypi.org/project/easyrelease/#description"><img src="https://img.shields.io/pypi/v/easyrelease?color=yellow&amp;label=pypi%20version" alt="PyPI"></a>
<a href="https://anaconda.org/pablormira/easyrelease"><img src="https://anaconda.org/pablormira/easyrelease/badges/version.svg" alt="conda"></a>
<a href="https://anaconda.org/pablormira/easyrelease"><img src="https://anaconda.org/pablormira/easyrelease/badges/platforms.svg" alt="plattform"></a></p>

</div>
</div>
</div>
<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<h2 id="How-to-install">How to install<a class="anchor-link" href="#How-to-install"> </a></h2>
Expand Down Expand Up @@ -98,6 +107,11 @@ <h4 id="Anaconda-credentials">Anaconda credentials<a class="anchor-link" href="#
<div class="highlight"><pre><span></span><span class="na">username</span> <span class="o">=</span> <span class="s">Your Anaconda username</span>
<span class="na">password</span> <span class="o">=</span> <span class="s">Your Anaconda password</span>
</pre></div>
<h4 id="CONDA_BLD_PATH">CONDA_BLD_PATH<a class="anchor-link" href="#CONDA_BLD_PATH"> </a></h4><blockquote><p>Only for Linux users and only in case of problems</p>
</blockquote>
<p>In case of problems concerning permission errors building your package via <code>build-conda-package</code> you may need to add the following line to your <code>~/.bashrc</code></p>
<div class="highlight"><pre><span></span><span class="nb">export</span> <span class="nv">CONDA_BLD_PATH</span><span class="o">=</span>/tmp/conda-bld
</pre></div>

</div>
</div>
Expand All @@ -111,6 +125,11 @@ <h3 id="Getting-started">Getting started<a class="anchor-link" href="#Getting-st
<li>Edit your in the previous step generated file <code>settings.ini</code></li>
<li>Edit your in the previous step generated file <code>.gh-release-config.yaml</code></li>
</ol>
<p><code>.gh-release-config.yaml</code> sets the title and keyword that will be used to assign your commits to a certain section in your GitHub release notes and changelog. So if for example you want all commits to be in your release notes without keyword matching, you could modify <code>.gh-release-config.yaml</code> as</p>
<div class="highlight"><pre><span></span><span class="nt">gh_categories</span><span class="p">:</span>
<span class="p p-Indicator">-</span> <span class="nt">title</span><span class="p">:</span> <span class="s">&quot;###</span><span class="nv"> </span><span class="s">Commits:&quot;</span>
<span class="nt">keyword</span><span class="p">:</span> <span class="s">&quot;&quot;</span>
</pre></div>
<p>Each time you want to make a GitHub release:</p>
<ol>
<li>Run <code>gh-release</code> to make a GitHub release</li>
Expand All @@ -137,6 +156,41 @@ <h4 id="For-packages">For packages<a class="anchor-link" href="#For-packages"> <
<li>Run <code>upload-conda-package</code> to publish your conda package</li>
</ol>

</div>
</div>
</div>
<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<h2 id="Versioning">Versioning<a class="anchor-link" href="#Versioning"> </a></h2><p>We version our package via <a href="https://semver.org">semantic versioning</a>, i.e.,</p>
<ul>
<li>We use three digits separated by points x1.x2.x3, e.g. 0.5.1</li>
<li>We increase x1 (the major version) if we introduce breaking changes<ul>
<li>Exception: Versions with 0 at the beginning (e.g. 0.5.1) mean that the package is not stable yet and therefore every new feature could be a breaking change</li>
</ul>
</li>
<li>We increase x2 (the minor version) if we introduce a new feature</li>
<li>We increase x3 (the patch version) if we fix a bug</li>
</ul>
<p>New documentation, refactoring / maintenance of code and admin tasks do not change the versions.</p>
<p>You can follow the changes introduced by each version in our <a href="https://github.com/PabloRMira/easyrelease/blob/main/CHANGELOG.md">CHANGELOG</a></p>

</div>
</div>
</div>
<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<h2 id="Differences-to-fastrelease">Differences to <a href="https://github.com/fastai/fastrelease">fastrelease</a><a class="anchor-link" href="#Differences-to-fastrelease"> </a></h2><p>This package was inspired by the <a href="https://github.com/fastai/fastrelease">fastrelease</a> package but it differs from it in the way it generates the release notes.</p>
<p><code>easyrelease</code> generates the release notes out of the commit messages whereas <code>fastrelease</code> generates the release notes out of GitHub issues.</p>
<p>This package was also motivated by the fact that <code>fastrelease</code> did not work for me out of the box in my first attempt and I really liked the idea of automating releases and package publishing.</p>

</div>
</div>
</div>
<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<h2 id="Compatibility-with-nbdev">Compatibility with <a href="https://github.com/fastai/nbdev">nbdev</a><a class="anchor-link" href="#Compatibility-with-nbdev"> </a></h2><p>This package was developed and is compatible with the <a href="https://github.com/fastai/nbdev">nbdev</a> framework but it also works for ordinary project development without notebooks.</p>
<p>In the case you want to develop your project with <code>nbdev</code> you need to first initialize your project via <code>nbdev</code> and afterwards run <code>easyrelease-init</code>. This is because the <code>settings.ini</code> we initialize for your project is a proper / strict subset of the <code>settings.ini</code> from <code>nbdev</code></p>

</div>
</div>
</div>
Expand Down
73 changes: 72 additions & 1 deletion nbs/index.ipynb
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,14 @@
{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"[![PyPI](https://img.shields.io/pypi/v/easyrelease?color=yellow&label=pypi%20version)](https://pypi.org/project/easyrelease/#description)\n",
"[![conda](https://anaconda.org/pablormira/easyrelease/badges/version.svg)](https://anaconda.org/pablormira/easyrelease)\n",
"[![plattform](https://anaconda.org/pablormira/easyrelease/badges/platforms.svg)](https://anaconda.org/pablormira/easyrelease)"
]
},
{
"cell_type": "markdown",
"metadata": {},
Expand Down Expand Up @@ -111,7 +120,17 @@
"```ini\n",
"username = Your Anaconda username\n",
"password = Your Anaconda password\n",
"```"
"```\n",
"\n",
"#### CONDA_BLD_PATH\n",
"\n",
"> Only for Linux users and only in case of problems\n",
"\n",
"In case of problems concerning permission errors building your package via `build-conda-package` you may need to add the following line to your `~/.bashrc`\n",
"\n",
"```bash\n",
"export CONDA_BLD_PATH=/tmp/conda-bld\n",
"```\n"
]
},
{
Expand All @@ -129,6 +148,15 @@
"2. Edit your in the previous step generated file `settings.ini`\n",
"3. Edit your in the previous step generated file `.gh-release-config.yaml`\n",
"\n",
"`.gh-release-config.yaml` sets the title and keyword that will be used to assign your commits to a certain section in your GitHub release notes and changelog. So if for example you want all commits to be in your release notes without keyword matching, you could modify `.gh-release-config.yaml` as\n",
"\n",
"```yaml\n",
"gh_categories:\n",
" - title: \"### Commits:\"\n",
" keyword: \"\"\n",
"```\n",
"\n",
"\n",
"Each time you want to make a GitHub release:\n",
"\n",
"1. Run `gh-release` to make a GitHub release\n",
Expand All @@ -154,6 +182,49 @@
"5. Run `build-conda-package` to build your conda package\n",
"7. Run `upload-conda-package` to publish your conda package"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Versioning\n",
"\n",
"We version our package via [semantic versioning](https://semver.org), i.e., \n",
"\n",
"* We use three digits separated by points x1.x2.x3, e.g. 0.5.1\n",
"* We increase x1 (the major version) if we introduce breaking changes\n",
" * Exception: Versions with 0 at the beginning (e.g. 0.5.1) mean that the package is not stable yet and therefore every new feature could be a breaking change\n",
"* We increase x2 (the minor version) if we introduce a new feature\n",
"* We increase x3 (the patch version) if we fix a bug\n",
"\n",
"New documentation, refactoring / maintenance of code and admin tasks do not change the versions.\n",
"\n",
"You can follow the changes introduced by each version in our [CHANGELOG](https://github.com/PabloRMira/easyrelease/blob/main/CHANGELOG.md)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Differences to [fastrelease](https://github.com/fastai/fastrelease)\n",
"\n",
"This package was inspired by the [fastrelease](https://github.com/fastai/fastrelease) package but it differs from it in the way it generates the release notes. \n",
"\n",
"`easyrelease` generates the release notes out of the commit messages whereas `fastrelease` generates the release notes out of GitHub issues.\n",
"\n",
"This package was also motivated by the fact that `fastrelease` did not work for me out of the box in my first attempt and I really liked the idea of automating releases and package publishing."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Compatibility with [nbdev](https://github.com/fastai/nbdev)\n",
"\n",
"This package was developed and is compatible with the [nbdev](https://github.com/fastai/nbdev) framework but it also works for ordinary project development without notebooks.\n",
"\n",
"In the case you want to develop your project with `nbdev` you need to first initialize your project via `nbdev` and afterwards run `easyrelease-init`. This is because the `settings.ini` we initialize for your project is a proper / strict subset of the `settings.ini` from `nbdev`"
]
}
],
"metadata": {
Expand Down

0 comments on commit 87a37fd

Please sign in to comment.