Releasing
Once your module is ready to go, and you’ve written all the necessary tests, you want to open it to the world. This page will take you through the necessary steps to make sure your module can be used by others.
Meta files in the repository
To be accepted by the portal, your repository needs to meet community standards. This means you’ll need to ensure your repository has the following files:
-
CHANGELOG.md - A changelog to keep track of the changes between releases of your module. This should look something like… .Example
CHANGELOG.mdfile
-
CODE_OF_CONDUCT.md. Feel free to write your own, but here is the one we use for all our projects.
-
CONTRIBUTING.md. A description of how to contribute to the project. Ours can be found here.
-
LICENCE.md. The licence for your project. This will nearly always be the GNU General Public License v3.0, found here.
-
README.md. A description of your module. A template can be found here.
-
composer.json. You will probably already have this file in your module, but you need to make sure the name matches the name you want, and the description matches your module. Try and avoid using 'bristol-su' - use your own name or company name instead!
-
.gitattributes. This specifies (amongst other things) the files that aren’t needed for your code to run, and helps keep your module small when installed in the portal. .Example
.gitattributesfile
-
.github. This folder contains all meta related files for your github repository. By default, we give you issue templates and a workflow to automatically compile your javascript and sass on push. This means you don’t need to worry about running npm before pushing, as github will do this for you automatically! You may want to change the email/name in the workflow file though.
Documentation
To make your module as easy to use as possible, we strongly recommend documenting your work. To have your documentation included on the Bristol SU Documentation site, you must use antora.
This may sound scary, but it’s really simple to get started! We see documentation as being just as important as the code, and therefore should be kept in the same place. Generally this should be a /docs folder.
| The template module includes the documentation framework. |
Structure
The general structure of the docs folder should be as follows:
- /docs
- antora.yml (1)
- /modules
- /users (2)
- nav.adoc (3)
- /pages
- dummy-page.adoc (4)
- /images
- /admins (5)
- /setup (6)
- /developers (7)| 1 | The antora.yml file describes your documentation, giving it a version and a name. An example antora.yml file can be found below. |
| 2 | Where your user documentation lives. This should focus on how to use your module as a user |
| 3 | The navigation file. This defines the layout of the section. Each folder has one of these files. An example is given below. |
| 4 | An example page. Again, an example is given below. |
| 5 | The admin documentation. This should focus on how to use the admin side of the module |
| 6 | The setup documentation. This should focus on what each setting does, what the permissions do, what completion conditions are available etc. It should make creating a module instance using your module as easy as possible. |
| 7 | The developer documentation (optional). Contains any documentation you think may help future developers, or yourself. |
Releasing Documentation
You should use branches to keep track of your documentation versions. The following is a recommendation, but you may use other methods of tracking documentation versions.
Documentation should be written/updated along with the rest of your code on the develop branch. You may also use feature branches from the develop branch.
Work should then be merged into the master branch when ready. From here, it can be tagged with a release version.
A documentation branch should be made from the develop branch. A documentation branch should be called docs/v1.x, docs/v2.x etc, and we should only have a branch for major versions. For each new feature, we should update the docs on develop and merge it into the corresponding docs branch.
If we need to update old documentation for an older version, this can be done by editing the docs branch directly.
Releasing a version of your module
Once your module is in a state to be released, you should release a version. This includes:
-
Updating your changelog to represent any changes made
-
Clicking on 'Create a new release' on github
-
Creating a tag (e.g. v1.0.1). The release title should also be the name of the tag, and the description should be similar to your changelog. We use the following template for the description
# [v1.0.1 - 16/06/2020]
### Added
- Describe changes here
### Removed
- These changes should be the same as your changelog
[v1.0.1 - 16/06/2020]: https://github.com/username/repo/compare/v1.0.0...v1.0.1Making your module downloadable
In order to allow others to use your module, it must be published on a platform such as github then pulled through to a package management platform. We use https://packagist.org. Having created an account, submit your repository on the website. This will allow others to run 'composer require' to pull in your module.
Pull requests
At this point, you’re ready to go! All that’s left is to let other portal users know your module exists. To do this, you should submit a pull request to both the portal repository and the documentation repository.
Portal repository
The point of this pull request is to automatically include your module in all fresh installs of the portal. This is by far the best way to deploy your module - any users of the portal will be able to use your module.
-
Create a fork of the portal repository by clicking 'Fork' here.
-
Add your module using
composer require. -
Push your changes to your forked repository on Github.
-
Create a pull request, keeping the default base branch and changing the compare branch to your forked branch. You should see two files changed -
composer.jsonandcomposer.lock. -
Create the pull request. Set the title to be New Module: Module Name, and use the following template for the description
# Module Name
My Module
# What does this module do?
A brief description of what your module does
# Is your module up to our community standards?
- [x] I've written tests for the module
- [ ] I've written documentation for the moduleDocumentation Repository
Having written documentation, you can merge it into our documentation site.
-
Create a fork of the documentation site by clicking 'Fork' here.
-
Edit the
antora-playbook.ymland add the following under the module section in the content → sources attribute.- url: https://github.com/username/module-repository start_path: docs branches: [master, docs/*] -
Push your changes to your forked repository on Github
-
Create a pull request, keeping the default base branch and changing the compare branch to your forked branch. You should see one file changed -
antora-playbook.yaml. -
Create the pull request. Set the title to be Module Documentation: Module Name. You may leave the description blank.
Once we approve the request, it may take up to two hours to merge your documentation in with the documentation site. If you ever make changes to your documentation, they may also take up to two hours to propagate. You will only ever have to push the changes to your repository though - the documentation will pick up on changes itself.