ā””ā”€ā”€ README.md /README.md: -------------------------------------------------------------------------------- 1 | # Luarocks :purple_heart: Neovim 2 | 3 | A simple sample repository showing how to push your Neovim plugins to luarocks. 4 | 5 | For more information about the usefulness of a real package manager check the following blogs 6 | by Marc Jakobi: 7 | - [Publish your plugins to luarocks](https://mrcjkb.dev/posts/2023-01-10-luarocks-tag-release.html) 8 | - [Test your Neovim plugins with luarocks & busted](https://mrcjkb.dev/posts/2023-06-06-luarocks-test.html) 9 | 10 | My favourite quote from the blog: 11 | > Iā€™m a strong believer that we need plugin authors to publish their packages to LuaRocks before package managers start supporting it. Just like we had cars before petrol stations, and electric vehicles before charging infrastructure. 12 | 13 | # Getting Started 14 | 15 | Pushing your Neovim plugin to luarocks is a very simple process, so let's get going! 16 | 17 | ## Setting up a Luarocks Account 18 | 19 | First of all, visit https://luarocks.org and register an account. They support registration via a github account, 20 | which is arguably the most convenient. You may also opt for a simple username/password login. 21 | 22 | Next up, let's get ourselves an API key that we will use to publish our plugin to luarocks. 23 | 24 | ### Creating an API Key 25 | 26 | 1. Once you're logged in, head over to your settings. 27 | 28 | ![step 1](https://github.com/nvim-neorg/neorg/assets/76052559/727c325f-a9a8-493c-811f-b06871b6eabe) 29 | 2. Select the `API keys` section. 30 | 31 | ![step 2](https://github.com/nvim-neorg/neorg/assets/76052559/392327eb-08b3-479e-8047-c2e78b21e5d8) 32 | 3. Press `Generate New Key`, wait a bit, and copy the newly provided key! If you ever feel like 33 | the key has been stolen, you can revoke it here too. **Be sure to copy this key somewhere safe! We'll need it for later.** 34 | 35 | ![step 3](https://github.com/nvim-neorg/neorg/assets/76052559/591db8fe-472f-4847-a4f1-29d7478c114c) 36 | 37 | # The Semantic Versioning Scheme 38 | 39 | Luarocks versions its packages using [semver](https://semver.org/). The versioning follows a `major.minor.patch` 40 | scheme (e.g. `1.0.0`) - the major version is increased on every breaking change, the minor is increased 41 | on every feature release, and the patch is increased on every bug fix. 42 | 43 | We would like our Neovim plugins to also follow this versioning scheme, so let's set up a tool that will 44 | do it for us. 45 | 46 | ## Installing Release-Please (recommended) 47 | 48 | Because of the way we'll be setting up the workflow later on, it is recommended that you install [`release-please`](https://github.com/googleapis/release-please-action), 49 | a tool that automates the semver process. All you do is write commits in the [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) 50 | style (for example `fix: annoying bug` or `feat(ui): add new buttons`) and release-please generates a new release 51 | version in the form of a pull request to your repository. 52 | 53 | > [!NOTE] 54 | > The pull request made by the Github action gets updated on every new commit that you make - this means you control 55 | when a new version of your plugin is published by **merging the pull request**. 56 | > 57 | > When you do this, a new tag and release will be created on your repository, which is a critical step. 58 | 59 | In your repository root (where the `.git` directory is located) create a file under `.github/workflows/release-please.yml`. 60 | Paste the following contents into the file: 61 | ```yml 62 | name: Release Please 63 | 64 | on: 65 | push: 66 | branches: 67 | - main 68 | - master 69 | workflow_dispatch: 70 | 71 | permissions: 72 | contents: write 73 | pull-requests: write 74 | 75 | jobs: 76 | release: 77 | name: release 78 | runs-on: ubuntu-latest 79 | steps: 80 | - uses: googleapis/release-please-action@v4 81 | with: 82 | token: ${{ secrets.PAT }} 83 | release-type: simple 84 | ``` 85 | 86 | ### Generating a PAT (Personal Access Token) 87 | 88 | Because of Github we must generate a personal access token for our account (this will allow the luarocks workflow to be triggered 89 | by the release-please workflow). The process is quite simple, so let's get it over with. 90 | 91 | 1. Navigate to your Account -> Settings. 92 | 93 | ![settings](https://github.com/nvim-neorocks/sample-luarocks-plugin/assets/76052559/52cce7d0-b53c-467f-a3d9-a1bd6a1e1614) 94 | 2. Navigate to the "Developer Settings" tab on the very bottom of the Settings tab. 95 | 96 | ![image](https://github.com/nvim-neorocks/sample-luarocks-plugin/assets/76052559/0452ab2a-3f2f-4162-a8f4-411ba6bd2f37) 97 | 3. Make your way over to Personal Access Tokens -> Tokens (classic). We won't need fine-grained tokens for this simple task. 98 | 99 | ![image](https://github.com/nvim-neorocks/sample-luarocks-plugin/assets/76052559/863a5358-551c-4f44-b31b-85bb906cbc21) 100 | 4. Generate a new classic token. 101 | 102 | ![image](https://github.com/nvim-neorocks/sample-luarocks-plugin/assets/76052559/72693b75-1a65-4bb7-8e01-bb256aa4db15) 103 | 5. Modify the highlighted sections to the values shown on screen. 104 | 105 | ![image](https://github.com/nvim-neorocks/sample-luarocks-plugin/assets/76052559/534f49a0-d46d-422e-9c29-92d6f54dd640) 106 | 6. Press "Generate Token"! 107 | 7. **Copy your PAT to the same place where you stored your Luarocks API key**. Make sure it's somewhere safe! 108 | 109 | ![image](https://github.com/nvim-neorocks/sample-luarocks-plugin/assets/76052559/46c8d326-5534-447e-9268-670b872e3144) 110 | 111 | 112 | ## Publishing our `release-please` Workflow 113 | 114 | Afterwards, in your Github repository, run: 115 | - `git add .github/` 116 | - `git commit -m "ci: add release-please workflow"` 117 | - `git push` 118 | 119 | Congratulations, you've just set up `release-please`! It will now run in the background and after a while will create a pull 120 | request to your repository. We recommend that you DO NOT merge the pull request yet, but don't be afraid if you already did, 121 | you'll just need to run an extra command later in the tutorial. 122 | 123 | # Publishing to Luarocks 124 | 125 | After your repository has a working versioning scheme we may now move on to actually publishing our plugin to luarocks. 126 | 127 | It is recommended that your repository has as much metadata as possible (a license that is detected by github on the right side 128 | of your plugin's page, a repo title/description, github topics etc.) in your Github repository. 129 | 130 | Time to add our API key! 131 | 132 | ## Adding our API Key 133 | 134 | 5. Navigate to your Github repository and enter its settings. 135 | 136 | ![step 5](https://github.com/vhyrro/sample-luarocks-plugin/assets/76052559/3fab5791-189f-42cb-b8b2-824af45a114d) 137 | 138 | 6. In the settings go to `Security > Secrets and variables > Actions`. 139 | 140 | ![step 6](https://github.com/vhyrro/sample-luarocks-plugin/assets/76052559/ab8ca077-3f8a-4263-9583-2abcebdf9e6a) 141 | 7. Click `New repository secret`, almost there! 142 | 143 | ![step 7](https://github.com/vhyrro/sample-luarocks-plugin/assets/76052559/a67ddd29-5021-4d45-ae74-8a40507ccc51) 144 | 8. Name the secret `LUAROCKS_API_KEY` (make sure it's spelled exactly like this!). In the `Secret` field paste 145 | the API key you copied from the first step of the tutorial. 146 | 147 | ![step 8](https://github.com/vhyrro/sample-luarocks-plugin/assets/76052559/48590516-cf03-43a4-9ded-575c5a63caf5) 148 | 149 | Click `Add secret` and there you go! This secret is only visible to you (the 150 | repo owner) and administrators of your repository, so don't be afraid of anyone using it without your consent! 151 | 152 | > [!IMPORTANT] 153 | > If you also set up `release-please` earlier in the tutorial, create *another* secret called `PAT` (make sure it's called 154 | > exactly like this!). In the `Secret` field paste in your **Github Personal Access Token** that you copied earlier. 155 | 156 | ## Setting up `luarocks-tag-release` 157 | 158 | Similarly to the `release-please` setup process, create a `.github/workflows/luarocks.yml` file from the root of your repo. 159 | 160 | Paste the following into the file: 161 | ```yml 162 | name: Push to Luarocks 163 | 164 | on: 165 | push: 166 | tags: # Will upload to luarocks.org when a tag is pushed 167 | - "*" 168 | pull_request: # Will test a local install without uploading to luarocks.org 169 | workflow_dispatch: 170 | 171 | jobs: 172 | luarocks-upload: 173 | runs-on: ubuntu-22.04 174 | steps: 175 | - uses: actions/checkout@v4 176 | - name: LuaRocks Upload 177 | uses: nvim-neorocks/luarocks-tag-release@v7 178 | env: 179 | LUAROCKS_API_KEY: ${{ secrets.LUAROCKS_API_KEY }} 180 | with: 181 | # Optional: You can specify dependencies, etc. here 182 | dependencies: | 183 | plenary.nvim 184 | foo.nvim 185 | ``` 186 | 187 | If your plugin depends on a tree-sitter parser, you should add the tools 188 | required to build the parser to your workflow so that luarocks-tag-release can test 189 | the installation of your package before uploading. 190 | 191 | Example: 192 | 193 | ```yaml 194 | steps: 195 | - uses: actions/checkout@v4 196 | - name: Install C/C++ Compiler 197 | uses: rlalik/setup-cpp-compiler@master 198 | with: 199 | compiler: clang-latest 200 | # Required to build tree-sitter parsers 201 | - name: Install tree-sitter CLI 202 | uses: baptiste0928/cargo-install@v3 203 | with: 204 | crate: tree-sitter-cli 205 | - name: LuaRocks Upload 206 | uses: nvim-neorocks/luarocks-tag-release@v7 207 | env: 208 | LUAROCKS_API_KEY: ${{ secrets.LUAROCKS_API_KEY }} 209 | with: 210 | dependencies: | 211 | tree-sitter-rust 212 | ``` 213 | 214 | Afterwards, run: 215 | - `git add .github/` 216 | - `git commit -m "ci: add luarocks workflow"` 217 | - `git push` 218 | 219 | Just one more thing now! 220 | 221 | ## Publish a Release of your Plugin 222 | 223 | Now that we have everything set up, all the pieces can fall into place. 224 | Go to the Pull Requests tab in your repository where `release-please` should have created a PR for you 225 | (assuming your were using conventional commits). Merge that pull request, and the chain reaction should begin! 226 | First, release-please should (after a minute or so) publish a new tag with a version. Afterwards, the luarocks 227 | workflow should trigger and your plugin should end up on `luarocks.org`! 228 | 229 | # Troubleshooting 230 | 231 | ### I already merged the release-please PR earlier! 232 | 233 | If you merged your PR beforehand, don't worry. We'll need to install the `gh` CLI tool in order to run 234 | the workflow manually. There are many resources for that online, just search "setting up the gh cli tool" in 235 | your favourite search engine! After you are logged in, run `gh workflow run luarocks.yml`. After a minute you should 236 | see your plugin on luarocks :D 237 | --------------------------------------------------------------------------------