]>
Commit | Line | Data |
---|---|---|
91a21c27 | 1 | # Release Shaarli |
2 | ||
3 | ## Requirements | |
4 | ||
5 | This guide assumes that you have: | |
6 | ||
7 | - a GPG key matching your GitHub authentication credentials/email (the email address identified by the GPG key is the same as the one in your `~/.gitconfig`) | |
8 | - a GitHub fork of Shaarli | |
9 | - a local clone of your Shaarli fork, with the following remotes: | |
10 | - `origin` pointing to your GitHub fork | |
11 | - `upstream` pointing to the main Shaarli repository | |
12 | - maintainer permissions on the main Shaarli repository, to: | |
13 | - push the signed tag | |
14 | - create a new release | |
15 | - [Composer](https://getcomposer.org/) needs to be installed | |
16 | - The [venv](https://docs.python.org/3/library/venv.html) Python 3 module needs to be installed for HTML documentation generation. | |
17 | ||
18 | ## Release notes and `CHANGELOG.md` | |
19 | ||
20 | GitHub allows drafting the release notes for the upcoming release, from the [Releases](https://github.com/shaarli/Shaarli/releases) page. This way, the release note can be drafted while contributions are merged to `master`. See http://keepachangelog.com/en/0.3.0/ for changelog formatting. | |
21 | ||
22 | `CHANGELOG.md` should contain the same information as the release note draft for the upcoming version. Update it to: | |
23 | ||
24 | - add new entries (additions, fixes, etc.) | |
25 | - mark the current version as released by setting its date and link | |
26 | - add a new section for the future unreleased version | |
27 | ||
28 | ```bash | |
29 | ## [v0.x.y](https://github.com/shaarli/Shaarli/releases/tag/v0.x.y) - UNRELEASES | |
30 | ||
31 | ### Added | |
32 | ||
33 | ### Changed | |
34 | ||
35 | ### Fixed | |
36 | ||
37 | ### Removed | |
38 | ||
39 | ### Deprecated | |
40 | ||
41 | ### Security | |
42 | ||
43 | ``` | |
44 | ||
45 | ||
46 | ## Update the list of Git contributors | |
47 | ||
48 | ```bash | |
49 | $ make authors | |
50 | $ git commit -s -m "Update AUTHORS" | |
51 | ``` | |
52 | ||
53 | ## Create and merge a Pull Request | |
54 | ||
55 | Create a Pull Request to marge changes from your remote, into `master` in the community Shaarli repository, and have it merged. | |
56 | ||
57 | ||
58 | ## Create the release branch and update shaarli_version.php | |
59 | ||
60 | ```bash | |
61 | # fetch latest changes from master to your local copy | |
62 | git checkout master | |
63 | git pull upstream master | |
64 | ||
65 | # If releasing a new minor version, create a release branch | |
66 | $ git checkout -b v0.x | |
67 | ||
68 | # Bump shaarli_version.php from dev to 0.x.0, **without the v** | |
69 | $ vim shaarli_version.php | |
70 | $ git add shaarli_version | |
71 | $ git commit -s -m "Bump Shaarli version to v0.x.0" | |
72 | $ git push upstream v0.x | |
73 | ``` | |
74 | ||
75 | ## Create and push a signed tag | |
76 | ||
77 | Git [tags](http://git-scm.com/book/en/v2/Distributed-Git-Maintaining-a-Project#Tagging-Your-Releases) are used to identify specific revisions with a unique version number that follows [semantic versioning](https://semver.org/) | |
78 | ||
79 | ```bash | |
80 | # update your local copy | |
81 | git checkout v0.5 | |
82 | git pull upstream v0.5 | |
83 | ||
84 | # create a signed tag | |
85 | git tag -s -m "Release v0.5.0" v0.5.0 | |
86 | ||
87 | # push the tag to upstream | |
88 | git push --tags upstream | |
89 | ``` | |
90 | ||
91 | Here is how to verify a signed tag. [`v0.5.0`](https://github.com/shaarli/Shaarli/releases/tag/v0.5.0) is the first GPG-signed tag pushed on the Community Shaarli. Let's have a look at its signature! | |
92 | ||
93 | ```bash | |
94 | # update the list of available tags | |
95 | git fetch upstream | |
96 | ||
97 | # get the SHA1 reference of the tag | |
98 | git show-ref tags/v0.5.0 | |
99 | # gives: f7762cf803f03f5caf4b8078359a63783d0090c1 refs/tags/v0.5.0 | |
100 | ||
101 | # verify the tag signature information | |
102 | git verify-tag f7762cf803f03f5caf4b8078359a63783d0090c1 | |
103 | # gpg: Signature made Thu 30 Jul 2015 11:46:34 CEST using RSA key ID 4100DF6F | |
104 | # gpg: Good signature from "VirtualTam <virtualtam@flibidi.net>" [ultimate] | |
105 | ``` | |
106 | ||
107 | ## Publish the GitHub release | |
108 | ||
109 | - In the `master` banch, update version badges in `README.md` to point to the newly released Shaarli version | |
110 | - Update the previously drafted [release](https://github.com/shaarli/Shaarli/releases) (notes, tag) and publish it | |
111 | - Profit! | |
112 | ||
113 | ||
114 | ## Generate full release zip archives | |
115 | ||
116 | Release archives will contain Shaarli code plus all required third-party libraries. They are useful for users who: | |
117 | ||
118 | - have no SSH access, no possibility to install PHP packages/server extensions, no possibility to run scripts (shared hosting) | |
119 | - do not want to install build/dev dependencies on their server | |
120 | ||
121 | `git checkout` the appropriate branch, then: | |
122 | ||
123 | ```bash | |
124 | # checkout the appropriate branch | |
125 | git checkout 0.x.y | |
126 | # generate zip archives | |
127 | make release_archive | |
128 | ``` | |
129 | ||
130 | This will create `shaarli-v0.x.y-full.tar`, `shaarli-v0.x.y-full.zip`. These archives need to be manually uploaded on the previously created GitHub [release](https://github.com/shaarli/Shaarli/releases). | |
131 | ||
132 | ||
133 | ### Update the `latest` branch | |
134 | ||
135 | ```bash | |
136 | # checkout the 'latest' branch | |
137 | git checkout latest | |
138 | # merge changes from your newly published release branch | |
139 | git merge v0.x.y | |
140 | # fix eventual conflicts with git mergetool... | |
141 | # run tests | |
142 | make test | |
143 | # push the latest branch | |
144 | git push upstream latest | |
145 | ``` |