We are really glad you've decided to contribute to this project ✌
As a contributor, here are the guidelines we'd like you to follow:
- Code of conduct
- How can I contribute?
- Using the issue tracker
- Submitting a Pull Request
- Coding rules
- Working with the code
We also recommend reading How to Contribute to Open Source
We firmly believe that software development is an art and as such, having fun should always be a priority. This, of course, can only be achieved if there is respect and tolerance among all parties involved.
Please read and follow the Code of conduct
If you're new to GitHub issues, you might want to limit your search to `label: "good first issue".
As a user, you're the perfect candidate to help us improve the documentation: typo corrections, clarifications, recipes, etc.
Take a look at the documentation issues that need help. Please follow the Documentation guidelines.
Some issues are created without information requested in the Bug report guideline. Help make them easier to resolve by adding any relevant information.
Issues with the discussion label are meant to discuss the implementation of new features. Participating in the discussion is a good opportunity to get involved and influence the future direction of this package.
Confirmed bugs and ready-to-implement features are marked with the help wanted label. Post a comment on the issue to indicate you would like to work on it and to request help from the @rb-mwindh/ngx-theme-manager/maintainers and the community.
The issue tracker is the channel for bug reports, feature requests and submitting pull requests.
Please use the Get help section for support, troubleshooting and questions.
Before opening an issue or a Pull Request, please use the Github issue search to make sure the bug or feature hasn't been already reported or fixed.
A good bug report shouldn't leave others needing to chase you for more information. Please try to be as detailed as possible in your report and fill the information requested in the Bug report template.
Although we try really hard, we can't foresee all imaginable use cases. So if you say to yourself, "Wouldn't it be nice if this package could...", then you should document this idea as quick as possible.
We invite you to submit your feature requests to our issue tracker. Please try to describe your idea as detailed as possible. As a little help we have prepared a Feature request template.
Writing good and understandable documentation is a difficult art. Although we always strive for the highest possible quality, there will always be features not clearly documented or not documented at all.
You are welcome to point out such shortcomings to us. We have prepared a documentation request template to lower the hurdle as much as possible.
Even with the best tool, questions arise from time to time. Since we want to make your user experience as smooth as possible, we are very interested in your questions.
As a communication channel for technical questions, we offer you a question template.
Good pull requests, whether patches, improvements, or new features, are a fantastic help. They should remain focused in scope and avoid containing unrelated commits.
Please ask first before embarking on any significant pull requests (e.g., implementing features, refactoring code), otherwise you risk spending a lot of time working on something that the project's developers might not want to merge into the project.
If you have never created a pull request before, this is your chance 😄. Here is a great tutorial on how to send one :)
Here is a summary of the steps to follow:
- Set up the workspace
- If you cloned a while ago, get the latest changes from upstream and update dependencies:
$ git checkout main
$ git pull upstream main
$ npm run init- Create a new topic branch (off the main project development branch) to contain your feature, change or fix:
$ git checkout -b <topic-branch-name>- Make your code changes, following the Coding rules
- Push your topic branch up to your fork:
$ git push origin <topic-branch-name>- Open a Pull Request with a clear title and description.
Tips:
- For ambitious tasks, open a Pull Request as soon as possible with the
[WIP]prefix in the title, in order to get feedback and help from the community. - Allow the maintainers to make changes to your Pull Request branch. This way, we can rebase it and make some minor changes if necessary. All changes we make will be done in new commits, and we'll ask for your approval before merging them.
To ensure consistency and quality throughout the source code, all code modifications must have:
- No linting errors
- A test for every possible case introduced by your code change
- 100% test coverage
- Valid commit message(s)
- Documentation for new features
- Updated documentation for modified features
To ensure consistency and quality, all documentation modifications must:
- Refer to brand in bold with proper capitalization, i.e. GitHub, Angular, npm
- Prefer tables over lists when listing key values, i.e. List of options with their description
- Use links
when you are referring to:
- a concept described somewhere else in the documentation, i.e. How to contribute
- a third-party product/brand/service, i.e. Fetch API
- an external concept or feature, i.e. Create a GitHub release
- Prefer Reference-style Links for external documents to have all external references in a single place
- Use the single backtick
codequoting for:- commands inside sentences, i.e. the
@rb-mwindh/ngx-theme-managercommand - programming language keywords, i.e.
function,async,String - packages or modules, i.e. The
@rb-mwindh/ngx-theme-managermodule
- commands inside sentences, i.e. the
- Use the triple backtick
codeformatting for:- code examples
- configuration examples
- sequence of command lines
If possible, make atomic commits, which means:
- a commit should contain exactly one self-contained functional change
- a functional change should be contained in exactly one commit
- a commit should not create an inconsistent state (such as test errors, linting errors, partial fix, feature with documentation etc...)
A complex feature can be broken down into multiple commits as long as each one maintains a consistent state and consists of a self-contained change.
To ensure consistency and quality, we're using the Commitizen CLI to create commits. The workflow is pretty simple:
- Make your code changes
- Stage your code changes
$ git add .- Commit your changes using the Commitizen CLI
$ npm run commit- Answer all questions
Fork the project, clone your fork, configure the remotes and install the dependencies:
# Clone your fork of the repo into the current directory
$ git clone https://github.com/<your username>/ngx-theme-manager <repo-name>
# Navigate to the newly cloned directory
$ cd <repo-name>
# Assign the original repo to a remote called "upstream"
$ git remote add upstream https://github.com/rb-mwindh/ngx-theme-manager
# Initialize your workspace (set up commit hooks, etc.)
$ npm run initThis workspace provides a demo application to visually test your changes.
You may run this application locally to observe the result of your code changes while developing.
$ npm run startThis repository uses Prettier for formatting. Formatting is executed automatically on commit.
Please make sure that you've run the init script as described here.
If your IDE provides Prettier integration, you might want to activate formatting as on Save action.
This repository uses ESLint for linting. Linting is executed automatically on commit.
Please make sure that you've run the init script as described here.
This repository uses Jest for testing.
Before pushing your code changes make sure all tests pass and the coverage is 100%:
$ npm run testThis repository uses Commitizen CLI to help you create valid commit messages.
After staging your changes with git add, run npm run commit or use git-cz directly to start the interactive commit
message CLI.