Welcome! We are excited that you are interested in contributing to our project! However, there are some things you might need to know, so please browse the following:
There are multiple ways of getting involved:
As a new contributor, you are in an excellent position to give us feedback to our project. For example, you could:
-
Fix or report a bug.
-
Suggest enhancements to code, tests and documentation.
-
Report/fix problems found during installing or developer environments.
-
Add suggestions for something else that is missing.
Be nice and respectful to each other.
We follow the Contributor Covenant Code Of Conduct.
Please check briefly if there already exists an Issue with your topic. If so, you can just add a comment to that with your information instead of creating a new Issue.
To report bugs is a good and easy way to contribute.
To do this, open an Issue that summarizes the bug and set the label to "bug".
You want to contribute code, documentation or 'your fantastic thing x'. Great, however, there are some practical points to check to make sure that everything runs as smoothly as possible.
-
It is always best to discuss your plans beforehand, to ensure that your contribution is in line with our goals.
-
Check the list of open Issues. Either assign an existing issue to yourself, or create a new one that you would like to work on, and discuss your ideas and use cases.
-
Follow the projects' convention and style regarding test, code and documentation, commit style etc.
-
Follow the UX guidelines.
-
Follow the Accessibility guidelines.
-
The project can decide to decline a contribution not following the general project guidelines, or deemed to not fit into the general project goal/architecture.
-
Make sure you have an understanding of the Pull Request Lifecycle.
-
You agree to that in general, all contributions to this project will be released under the inbound=outbound norm, that is, they are submitted under the same terms as the project licenses. In a more formal way - 'Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of the projects License, without any additional terms or conditions.'
This project aims to comply to the principles outlined in the Standard for Public Code. The standard consists of a set of criteria that both the project itself and all contributions must align with. It is important to note that the standard is currently being worked on. The documentation is accessible via the following link: https://standard.publiccode.net/.
Generally speaking, you should fork this repository, make changes in your own fork, and then submit a pull-request. This workflow is common, maybe even expected if nothing else mentioned, and is called the Fork-and-Pull model
A practical example of such a workflow could be:
-
Fork the repository.
-
Create a topic branch from your forks main/master branch, i.e. myfeaturebranch
-
When creating a branch related to an existing issue, it’s recommended to follow a naming convention that includes the type of issue and the corresponding issue number. This can be achieved by using the format
{type}/{issue number}-descriptive-title`, such asenhancement/1-create-linkfor an enhancement issue with number 1. This naming convention helps to clearly associate the branch with the correct issue and allows for easier tracking of progress.
-
-
Push your changes to the topic branch (in your fork) of the repository, i.e
enhancement/10-my-feature-branch. -
Create the relevant tests. See the Testing Guidelines.
-
Open a new pull request to main project.
-
Mention the fixed issues in the Pull Request description.
-
Verify that all tests are passing.
-
Project maintainers might comment and give feedback on your Pull Request.
-
Approved PRs are merged, and the branch is deleted.
|
Note
|
Signoff and signing: Two similar terms for two different things A Signoff assures to the project that you have the right to contribute your content A Sign assures that the commit came from you |
A standard practice in the Open Source communities is the DCO - Developer Certificate of Origin. It is a lightweight way for a project for extra assurance that the contributor wrote and/or have the right to submit the contribution.
It is supersimple!
As part of filing a pull request you agree to the DCO, by just adding a sign off to your commit.
Technically, this is done by supplying the -s/--signoff flag:
Example:
$ git commit --signoff -m 'fix: add fix for superbug x'Optionally, you can also sign the commit with -S/--gpg-sign.
Besides extra trust, it also gives your commit a nice verified button in the UI on most Git platforms and further assures trust.
It requires that you have a GPG keypair set up, see Sign commit on GitHub with GPG key
`$ git commit --signoff --gpg-sign -m "fix: add fix for the bug"`Aim for a clear human readable commit history:
-
Does the project have a defined commit message practice, please follow that.
-
When making a commit related to an issue, it’s recommended to include the issue number in the commit message for easy traceability. The format of the commit message can be
{issue number}: Commit message, such as10: Added test for string concatenation. By following this convention, it will be easier to track the changes made to a specific issue, especially when the branch is merged. -
Make sure you Sign-Off your commits.
-
In general
-
Make commits of logical units.
-
Your commit messages should tell a human reader what will it do when the commit is applied.
-
Make your commit message/s easily human readable in an expected way:
-
A Conventional Commit example:
10: add a null pointer check to MyMethod parameter
Would be read as 'When this fix is applied it will add a null pointer check to MyMethod parameter'
-
-
Testing is an important part of the software development process, and should be done throughout the development cycle to ensure that your application works as intended on different platforms and environments.
-
Write Unit Tests that, preferrably, verify the behavior of small, isolated parts of your code.
-
Use a testing framework that is appropriate for your programming language and environment. In the case of this project, we use Jest.
-
Conduct Manual Testing on PC, MacOS, and Web: Manual testing involves manually executing your application and verifying its behavior.
-
Make sure that the project works on the intended version of Outlook. The add-in should work on Outlook 2016 and later. You can test on different versions of Outlook with the Office Deployment Tool.
It is important to ensure that the add-in remains easy to use for everyone, regardless of their technical proficiency. Therefore, the number of clicks required to achieve the intended outcome should not increase when new code is added to the project, except for essential changes that may require an increase in the number of clicks.
-
The repository uses the MIT license. This means that anyone can use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the software without restriction, provided that the original copyright notice and license are included.
-
Any imported libraries should also have licenses that are compatible with the MIT license.
-
The project follows the REUSE specification. When done with additions in your Pull Request, a simple way to lint the project is by running a REUSE-lint:
$ docker run --rm --volume $(pwd):/data fsfe/reuse lint-
Only use assets (such as images, audio files, video clips, etc.) that are licensed under a permissive license, such as Creative Commons, or that are in the public domain. This ensures that you have the right to use the assets without infringing on anyone’s copyright.
-
Always check the terms of the license before using an asset. Make sure that you are following any requirements or restrictions that are specified in the license.
-
If you are not sure about the licensing terms of an asset, do not use it. It is better to err on the side of caution and avoid potential legal issues.
If you discover a security issue, please bring it to our attention.
If the vulnerability is a widely known issue, such as one publically known from NIST/NVD it might be okay to file an public Issue.
However, if any uncertainty around this, please DO NOT file a public issue, see Security information for how to handle this.
Security reports are greatly appreciated.
Happy contributing!