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.
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
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
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
|The template module includes the documentation framework.|
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)
|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.|
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
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/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.
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.1
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.
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.
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
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 -
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 module
Having written documentation, you can merge it into our documentation site.
Create a fork of the documentation site by clicking 'Fork' here.
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 -
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.