The technical details on how to set up your local development environment for making changes to the castanet Hugo theme for podcasts.
- Set up your environment
- How can I help?
- Making changes
- Design Principles
- Local build and testing
- Continuous Integration
- Documentation
- Releasing
- Creating a new color theme
- Developer Certification of Origin (DCO)
Prerequisites:
make(note - this is not needed yet)gulpv4.0.0+nodejsandnpm- hugo v0.69.2+
Clone castanet from source into your working directory of choice:
$ mkdir -p ~/src/github.com/mattstratton/castanet
$ cd $_
$ git clone [email protected]:mattstratton/castanet.git .Working with a Hugo theme outside of a content-based repo has a few challenges. The castanet repo contains a directory called exampleSite, which is what is used for testing theme development. The config.toml for the exampleSite contains the following value:
themesdir = "../.."
This tells Hugo where to look for its theme directories. This requires Hugo 0.18 or later.
You will need to run your watch command from the exampleSite directory; use something like this:
hugo server -w --baseUrl="http://localhost:1313"
Change our remote to be named upstream:
$ git remote rename origin upstreamAdd your fork as origin:
$ git remote add fork [email protected]:you/castanet.githttps://docs.npmjs.com/getting-started/installing-node
npm install --global gulp
npm install
Sort the existing GitHub issues for the tag of help-wanted. These are issues that we need help with! If you are going to tackle one, please comment on the issue so folks know you are on it.
There are no automated tests, but it is recommended that you test manually by testing both row and grid configurations in the config.toml inside exampleSite.
Commit messages should be well formatted. Start your commit message with a title in the imperative, i.e., "Updates function foo" vs "Updated function foo". Capitalize it.
The title must be followed with a newline, then a more detailed description.
Please reference any GitHub issues on the last line of the commit message (e.g. See #123, Closes #123, Fixes #123).
An example:
Add parameter for new social network to guests
I created a new parameter for the fancy new social network that
everyone is using now.
Fixes #284
(inspired by Katrina Owen's excellent blog post)
Assuming that the you/castanet repo is at origin, and mattstratton/castanet is at upstream, here's how to create a pull request:
$ git checkout -b make-thing-awesome
$ git commit -a myfile.go
$ git commit -s -m "Make thing more awesome"
$ git push origin make-thing-awesome
Don't forget to keep up to date with upstream:
$ git fetch upstream
$ git reset --hard upstream/masterWe use Boostrap v4 as our basic framework.
All page templates should make use of the layouts/_default/baseof.html file. This file contains all wrappers for the content. Anything within the {{- block "main" . }} {{- end -}} section is what will be displayed on a sub-template. Include a {{ define "main" }} block in your template to include what should be rendered.
All CSS must be generated with SCSS. The SCSS files are located in static/scss.
This is the file that imports all the other SCSS files, including Bootstrap, font-awesome, jssocials, and the jquery oembed. It also imports our custom variables and any other customizations.
Note that this refers to files like blue-variables.scss or orange-variables.scss. There is no actual file named color-variables.scss
Use this to set any SCSS variables, or to over-ride any variables used by Bootstrap. You need one for each color theme created.
This is the only place you should declare custom SCSS or CSS code.
All Javascript files are combined using gulp. The source Javascript files can be located either in node_modules or static/js. They are combined and minified into static/castanet-min.js.
Inside the theme directory, run npm install.
Run gulp dev to build the compiled stylesheets and Javascript files
The castanet repo has hooks into CircleCI and Netlify. The CircleCI builds the site according the various configurations (row vs grid and with all the color schemes). If you're curious, you can check out the CircleCI configuration in .circleci/config.yml.
We use the Deploy Previews feature of Netlify. The config for this is at netlify.toml.
All changes are built by Netlify to http://sample-castanet.netlify.com/ once merged to master.
All changes should be driven by issues (this is because our changelog generator is issue-driven). So before you implement a bugfix or an enhancement, you should make sure an issue has been created and properly tagged. These are the issue labels that really matter:
Bug: Something is broken in the theme and needs fixing. These issues should be set with a label of bug, and will be tagged with ready when they are ready to be worked on.
Enhancement: Adding new functionality to the theme. These issues should be set with a label of enhancement, and will be tagged with ready when they are ready to be worked on.
Only repository contributors can add tags to issues; if you do not have permission to tag an issue, please prepend the title with [BUG] or [ENHANCEMENT] as appropriate.
If you use the issue templates when opening your issues, the proper titles and tags should be added for you!
These are the labels we use, and what they mean:
bug: Something is broken in the theme and needs fixing.enhancement: Add new functionality to the site/theme.do-not-merge: Only used by pull requests; means that this PR is a work in progress and not ready for merging.duplicate: This issue is handled by another issue. When marking an issue "duplicate", please link to the tracked issue.help wanted: This is a label for issues where the main contributors are actively seeking outside help.needs-review: Only used by pull requests; indicates that a review is required prior to merging.ready: This issue can/should be worked on. Issues not marked as "ready" means they haven't been prioritized.no-changelog: This issue/PR should be excluded from the changelog.question: Issues that are for discussion, not an actual bug or enhancement.
Please submit your proposed changes as a Pull Request against this repository. If the PR will resolve an issue, please add Fixes #123 to the PR. We also will label issues as bug or enhancement for proper CHANGELOG generation. For more details, see Linking a pull request to an issue using a keyword.
If you add a new feature, please do the following:
- Update the README to reflect how this field/feature is used (to assist with adding rows to our tables, we recommend the excellent Tables Generator tool).
- If possible, add this feature to the
exampleSite, for testing and display purposes.
See utils/README for instructions.
Adding a color theme is quite simple - you will need to generate two new files for the theme:
static/scss/<MYCOLOR>_variables.scssstatic/scss/<MYCOLOR.scss
The <MYCOLOR>_variables.scss file contains the Sass variables uses to build the stylesheet. <MYCOLOR> should refer to the name of the style as you will set it in the config.toml.
Licensing is very important to open source projects. It helps ensure the software continues to be available under the terms that the author desired.
This project uses the MIT license.
The license tells you what rights you have that are provided by the copyright holder. It is important that the contributor fully understands what rights they are licensing and agrees to them. Sometimes the copyright holder isn't the contributor, such as when the contributor is doing work on behalf of a company.
To make a good faith effort to ensure these criteria are met, we requires the Developer Certificate of Origin (DCO) process to be followed.
The DCO is an attestation attached to every contribution made by every developer. In the commit message of the contribution, the developer simply adds a Signed-off-by statement and thereby agrees to the DCO, which you can find below or at http://developercertificate.org/.
Developer's Certificate of Origin 1.1
By making a contribution to this project, I certify that:
(a) The contribution was created in whole or in part by me and I
have the right to submit it under the open source license
indicated in the file; or
(b) The contribution is based upon previous work that, to the
best of my knowledge, is covered under an appropriate open
source license and I have the right under that license to
submit that work with modifications, whether created in whole
or in part by me, under the same open source license (unless
I am permitted to submit under a different license), as
Indicated in the file; or
(c) The contribution was provided directly to me by some other
person who certified (a), (b) or (c) and I have not modified
it.
(d) I understand and agree that this project and the contribution
are public and that a record of the contribution (including
all personal information I submit with it, including my
sign-off) is maintained indefinitely and may be redistributed
consistent with this project or the open source license(s)
involved.
The DCO requires a sign-off message in the following format appear on each commit in the pull request:
Signed-off-by: George Bluth <[email protected]>
The DCO text can either be manually added to your commit body, or you can add either -s or --signoff to your usual git commit commands. If you forget to add the sign-off you can also amend a previous commit with the sign-off by running git commit --amend -s. If you've pushed your changes to Github already you'll need to force push your branch after this with git push -f.