]>
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 | |
831e974e A |
67 | # Otherwise just use the existing one |
68 | $ git checkout v0.x | |
69 | ||
70 | # Get the latest changes | |
71 | $ git merge master | |
72 | ||
73 | # Check that everything went fine: | |
74 | $ make test | |
91a21c27 | 75 | |
76 | # Bump shaarli_version.php from dev to 0.x.0, **without the v** | |
77 | $ vim shaarli_version.php | |
78 | $ git add shaarli_version | |
79 | $ git commit -s -m "Bump Shaarli version to v0.x.0" | |
80 | $ git push upstream v0.x | |
81 | ``` | |
82 | ||
83 | ## Create and push a signed tag | |
84 | ||
85 | 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/) | |
86 | ||
87 | ```bash | |
88 | # update your local copy | |
89 | git checkout v0.5 | |
90 | git pull upstream v0.5 | |
91 | ||
92 | # create a signed tag | |
93 | git tag -s -m "Release v0.5.0" v0.5.0 | |
94 | ||
95 | # push the tag to upstream | |
96 | git push --tags upstream | |
97 | ``` | |
98 | ||
99 | 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! | |
100 | ||
101 | ```bash | |
102 | # update the list of available tags | |
103 | git fetch upstream | |
104 | ||
105 | # get the SHA1 reference of the tag | |
106 | git show-ref tags/v0.5.0 | |
107 | # gives: f7762cf803f03f5caf4b8078359a63783d0090c1 refs/tags/v0.5.0 | |
108 | ||
109 | # verify the tag signature information | |
110 | git verify-tag f7762cf803f03f5caf4b8078359a63783d0090c1 | |
111 | # gpg: Signature made Thu 30 Jul 2015 11:46:34 CEST using RSA key ID 4100DF6F | |
112 | # gpg: Good signature from "VirtualTam <virtualtam@flibidi.net>" [ultimate] | |
113 | ``` | |
114 | ||
115 | ## Publish the GitHub release | |
116 | ||
117 | - In the `master` banch, update version badges in `README.md` to point to the newly released Shaarli version | |
118 | - Update the previously drafted [release](https://github.com/shaarli/Shaarli/releases) (notes, tag) and publish it | |
119 | - Profit! | |
120 | ||
121 | ||
122 | ## Generate full release zip archives | |
123 | ||
124 | Release archives will contain Shaarli code plus all required third-party libraries. They are useful for users who: | |
125 | ||
126 | - have no SSH access, no possibility to install PHP packages/server extensions, no possibility to run scripts (shared hosting) | |
127 | - do not want to install build/dev dependencies on their server | |
128 | ||
129 | `git checkout` the appropriate branch, then: | |
130 | ||
131 | ```bash | |
132 | # checkout the appropriate branch | |
133 | git checkout 0.x.y | |
134 | # generate zip archives | |
135 | make release_archive | |
136 | ``` | |
137 | ||
138 | 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). | |
139 | ||
140 | ||
141 | ### Update the `latest` branch | |
142 | ||
143 | ```bash | |
144 | # checkout the 'latest' branch | |
145 | git checkout latest | |
146 | # merge changes from your newly published release branch | |
147 | git merge v0.x.y | |
148 | # fix eventual conflicts with git mergetool... | |
149 | # run tests | |
150 | make test | |
151 | # push the latest branch | |
152 | git push upstream latest | |
153 | ``` |