Thank you for investing your time in contributing to our project! If you ever have any questions, feel free to contact us by creating an issue, starting a discussion, or directly via email at j-frost+billomat-ts@a3re.net.
That said, here are some pointers to get you started 🎊
Read our Code of Conduct to keep our community approachable and respectable.
To get an overview of the project, read the README. Here are some resources to help you get started with open source contributions:
- Finding ways to contribute to open source on GitHub
- Set up Git
- GitHub flow
- Collaborating with pull requests
billomat-ts is a TypeScript client for Billomat. Being that as it is, we test our code by hosting some example responses in the repository.
You'll find our source code in src/. index.ts exposes some of our code for importing in other projects. From there, there's code that defines how to construct an API client, some typings to provide insights into what Billomat API objects even look like, and the actual resource client, which uses superagent to perform requests.
We are super happy for any contribution you choose to make. This does not have to be programming code.
Discussions are often where the real work happens. Feel free to drop your thoughts in our discussions. If you're not confident in sharing your thoughts publicly, you can also contact j-frost via email at j-frost+billomat-ts@a3re.net. Do be aware that there may be a delay in response.
If you spot a problem, have a feature idea, or encounter a bug, first search whether an issue already exists. If a related issue doesn't exist, you can open a new one here.
Check out our existing issues here. Issues are labeled by our team. In general, the good first issue and help wanted labels are good places to start.
As a rule of thumb, please don't assign issues to people unless you know why.
When you've found an issue to work on, you're welcome to open a PR with a fix.
To add some changes to billomat-ts, unless you're a maintainer, you'll want to fork it first. There, you can create all manner of changes (for instance, a feature branch), and then later merge it back into our repo (usually referred to as "upstream").
Before making any functional code changes, you'll usually want to add a test that requires the changes you're looking to perform. This way, we're continually building more and more tests, and whenever we make a functional code change, all of our previous tests will verify that nothing broke (which would be called a regression).
For more information on TDD, check out this wiki article.
This way of working also makes it clear why we're building certain features. In a prototypical case, there'll be a discussion, followed by an issue, which will prompt a contributor to tackle it. They will write tests, which will force functional code to be written. There's a clear chain of motivation and we don't produce waste.
When adding code, especially enhancements, keep this principle in mind. It will produce more readable code, and help others understand what you had to do and why.
FCIS and TDD also interact in an interesting way. One criticism of TDD is that it's hard to decide when to start and stop testing things (ie when tests become too fine-grained and rigid). Splitting code into core and shell can counteract this problem of TDD to a certain degree by allowing us to test rigorously in the core, and avoid wasting time in the shell by just writing basic smoke tests.
There's a great talk called Boundaries by Gary Bernhardt from SCNA 2012 that explains the benefits of combining FCIS with TDD.
Please follow the spirit of these guidelines when writing commit messages.
In short:
- Capitalize the first word of the message.
- Use imperative mood (ie complete the sentence "This, commit, when applied, will...")
- Use 50 characters max on the first line, leave one empty, and then use 72 characters max on subsequent lines.
- Explain why you're adding the change, not what - we can see that from the commit's contents already.
- Reference issues and pull requests as appropriate ("see #5", "solves #22").
When you're finished with the changes, create a pull request, also known as a PR.
- Explain why you're submitting this PR. Think of this description as a summary of the commit messages, and adopt a similar style; Why over What.
- Don't forget to link your PR to its issue if you are solving one.
- Enable the checkbox to allow maintainer edits so the branch can be updated for a merge.
- Once you submit your PR, we'll review your proposal. We may ask questions or request additional information, or we may ask for changes to be made before the PR can be merged, either using suggested changes or pull request comments. Feel free to reply in-line on Github or add additional commits to resolve the comments.
- As you update your PR and apply changes, mark each conversation as resolved.
- If you run into any merge issues, checkout this git tutorial to help you resolve merge conflicts and other issues.
Thanks a ton for your contribution!
Depending on the nature of your PR, you may see your changes reflected soon on NPM and on Github's contributor page.
We rely on folks like you to make this project happen, so once again, from the bottom of our hearts, thanks a million :)