diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5911177970..deba56042d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,112 +1 @@ -# Contributing to GNU social - -First of all, if you're reading this intending to contribute to GNU social, -thanks! Free software development only happens when people like you take an -interest in giving back to the software they themselves use, and their -community. - -When contributing to this repository, please first discuss the change you wish to -make via issue, email, or any other method with the owners of this repository before -making a change. - -There's a few files you should read before going forward with a merge request -or a patch submission. They detail what this file touches on in brief. They -are: - -* `DOCUMENTATION/DEVELOPERS/CONTRIBUTING/coding_standards.md`: How your code should be structured and formatted to be - accepted into the GNU social codebase. -* `/DOCUMENTATION/DEVELOPERS/CONTRIBUTING/merge_request_checklist.md`: A quick checklist to review before submission. - - -## Merge Request Process - -1. Ensure you strip any trailing spaces off and checked the file with php-cs-fixer -2. Increase the version numbers in any examples files and the README.md to the new version that this - Pull Request would represent. The versioning scheme we use is [SemVer](http://semver.org/). -3. You may merge the Pull Request in once you have the sign-off of two other developers, or if you - do not have permission to do that, you may request the second reviewer to merge it for you. - - -## Coding Standards - -Since we will be expected to maintain your code once it's submitted, we ask you -to adhere to certain coding standards that make it easier for us to do so. If -code doesn't follow them, it will be rejected, so please read up on these. - - -## Bug Reports - -Please report bugs to the issue tracker at - Avoid assigning the labels -yourself, as these are for the development team to assign priority and area of -coverage to a subject. Please only submit something here if you are certain it -is a bug or represents a feature enhancement that we do not presently have. If -you are uncertain whether it's a bug, please feel free to ask -at #social IRC channel on freenode.net https://www.freenode.net/. - -When reporting a bug, please try to include as much information as possible, -including the environment being run on (if it's a common LAMP stack just give -us version numbers of the main stack components, that's fine), and the specific -error you get. If you do not get a client-facing error, please check the PHP -error_log and ensure there isn't something silently reported there, as well as -the GNU social log. Try to include steps to reproduce the error as well, as if -we cannot reproduce the error, we can't fix it! - -It is perfectly acceptable to reference the archive page of a discussion on the -mailing list for the bug report, by the way, as long as it includes all the -information we need for a bug report. - - -## Submitting Feature Requests / Enhancement Requests - -Social media is constantly evolving, and we welcome ideas about how we can -change and evolve GNU social to keep it the excellent piece of software that it -is. However, there are a few things we ask you do when submitting feature -requests: - -1. Understand that since we have a limited amount of developers and these people -contribute in their free time, we may prioritize things differently than you -value them. Oftentimes this is because certain requests involve less changes -to the existing codebase than others, and therefore this makes them easier -to add. -2. Please search the existing feature requests and enhancements to see if a -similar request exists. If one does but you have different ideas about how -to do it or what it should entail, please add a comment to the existing idea -rather than create a new one for your "version" of it. Duplicate submissions -mean we spend more time maintaining the tracker and less time actually -working on the codebase! -3. When outlining the way that you see something working, don't be afraid to be -as detailed as possible! We may not implement it exactly as you describe for -any variety of reasons, but the more concrete and fleshed out an idea is, the -easier it is for us to know what you want and be able to implement it in a -sane and secure fashion. -4. When describing a possible new idea and its mechanisms of operation, the key -words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", -"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the issue submission -are to be interpreted as described in RFC 2119. - - -Finally, and just as a call back to the first point, realize just because we -might not rush to implement something, doesn't mean that we don't want to -implement it! We would rather take the time to do something right the first -time, then hurriedly apply a new idea, or a fix, only to have to patch it later. - - -## Branch of Code Submissions - -Unless you've been specifically directed otherwise, all submissions of code -should be against the `nightly` branch, so make sure any modifications are based -on Nightly. - - -## Copyright / Licensing - -You acknowledge that by submitting code to GNU social, you are licensing it under -the GNU AGPLv3 unless there is an extenuating circumstance where it would be -licensed differently (such as modifications to an external library we include -such as Stomp). - -You also acknowledge that unless you assign a copyright explicitly, it will be -assumed to be assigned to GNU social. - -Thanks for considering submission, and happy hacking! +GNU social's contributing resources and instructions are made available at [DOCUMENTATION/DEVELOPERS](https://notabug.org/diogo/gnu-social/src/nightly/DOCUMENTATION/DEVELOPERS). diff --git a/DOCUMENTATION/DEVELOPERS/CONTRIBUTING/boilerplate.php b/DOCUMENTATION/DEVELOPERS/CONTRIBUTING/boilerplate.php index 3825a1c8b4..922dc5b7d0 100644 --- a/DOCUMENTATION/DEVELOPERS/CONTRIBUTING/boilerplate.php +++ b/DOCUMENTATION/DEVELOPERS/CONTRIBUTING/boilerplate.php @@ -27,7 +27,7 @@ namespace samples; defined('GNUSOCIAL') || die(); -require_once(__DIR__ . DIRECTORY_SEPARATOR . 'SampleHandler.php'); +require_once __DIR__ . DIRECTORY_SEPARATOR . 'SampleHandler.php'; /** * Description of this class. @@ -43,7 +43,7 @@ class MySampleClass * @param string $dummy_word just because. * @param int $result another just because. */ - public function __construct(string $dummy_word = '', int $result = null) + public function __construct(string $dummy_word = '', ?int $result = null) { global $demo; $this->niceWorld(); @@ -54,7 +54,7 @@ class MySampleClass * * @return string */ - public function niceWorld() : string + public function niceWorld(): string { return 'hello, world.'; } diff --git a/DOCUMENTATION/DEVELOPERS/CONTRIBUTING/merge_request_checklist.md b/DOCUMENTATION/DEVELOPERS/CONTRIBUTING/merge_request_checklist.md index e26c209dcf..4ef7866146 100644 --- a/DOCUMENTATION/DEVELOPERS/CONTRIBUTING/merge_request_checklist.md +++ b/DOCUMENTATION/DEVELOPERS/CONTRIBUTING/merge_request_checklist.md @@ -1,7 +1,7 @@ Submission Checklist ================================================================================ This document serves as a handy checklist for submitted merges and patches to -the postActiv project. Following it isn't a gaurantee a patch will be accepted, +the GNU social project. Following it isn't a gaurantee a patch will be accepted, but it will help you avoid common problems. 1. Ensure all code control paths in all functions return a value. diff --git a/DOCUMENTATION/DEVELOPERS/README.md b/DOCUMENTATION/DEVELOPERS/README.md new file mode 100644 index 0000000000..66fcc8e659 --- /dev/null +++ b/DOCUMENTATION/DEVELOPERS/README.md @@ -0,0 +1,112 @@ +# Contributing to GNU social + +First of all, if you're reading this intending to contribute to GNU social, +thanks! Free software development only happens when people like you take an +interest in giving back to the software they themselves use, and their +community. + +When contributing to this repository, please first discuss the change you wish to +make via issue, email, or any other method with the owners of this repository before +making a change. + +There's a few files you should read before going forward with a merge request +or a patch submission. They detail what this file touches on in brief. They +are: + +* `DOCUMENTATION/DEVELOPERS/CONTRIBUTING/coding_standards.md`: How your code should be structured and formatted to be + accepted into the GNU social codebase. +* `/DOCUMENTATION/DEVELOPERS/CONTRIBUTING/merge_request_checklist.md`: A quick checklist to review before submission. + + +## Merge Request Process + +1. Run php-cs-fixer. We also recommend you to use tools like phpstan, phpactor, phpcs and phpmd +2. Run our unit tests (`./vendor/bin/phpunit --testsuite Core`) +3. Respect our [VERSIONING](https://notabug.org/diogo/gnu-social/src/nightly/DOCUMENTATION/VERSIONING.md) system +4. You may merge the Merge Request in once you have the sign-off of two other developers, or if you + do not have permission to do that, you may request the second reviewer to merge it for you + + +## Coding Standards + +Since we will be expected to maintain your code once it's submitted, we ask you +to adhere to certain coding standards that make it easier for us to do so. If +code doesn't follow them, it will be rejected, so please read up on these. + + +## Bug Reports + +Please report bugs to the issue tracker at + Avoid assigning the labels +yourself, as these are for the development team to assign priority and area of +coverage to a subject. Please only submit something here if you are certain it +is a bug or represents a feature enhancement that we do not presently have. If +you are uncertain whether it's a bug, please feel free to ask +at #social IRC channel on freenode.net https://www.freenode.net/. + +When reporting a bug, please try to include as much information as possible, +including the environment being run on (if it's a common LAMP stack just give +us version numbers of the main stack components, that's fine), and the specific +error you get. If you do not get a client-facing error, please check the PHP +error_log and ensure there isn't something silently reported there, as well as +the GNU social log. Try to include steps to reproduce the error as well, as if +we cannot reproduce the error, we can't fix it! + +It is perfectly acceptable to reference the archive page of a discussion on the +mailing list for the bug report, by the way, as long as it includes all the +information we need for a bug report. + + +## Submitting Feature Requests / Enhancement Requests + +Social media is constantly evolving, and we welcome ideas about how we can +change and evolve GNU social to keep it the excellent piece of software that it +is. However, there are a few things we ask you do when submitting feature +requests: + +1. Understand that since we have a limited amount of developers and these people +contribute in their free time, we may prioritize things differently than you +value them. Oftentimes this is because certain requests involve less changes +to the existing codebase than others, and therefore this makes them easier +to add. +2. Please search the existing feature requests and enhancements to see if a +similar request exists. If one does but you have different ideas about how +to do it or what it should entail, please add a comment to the existing idea +rather than create a new one for your "version" of it. Duplicate submissions +mean we spend more time maintaining the tracker and less time actually +working on the codebase! +3. When outlining the way that you see something working, don't be afraid to be +as detailed as possible! We may not implement it exactly as you describe for +any variety of reasons, but the more concrete and fleshed out an idea is, the +easier it is for us to know what you want and be able to implement it in a +sane and secure fashion. +4. When describing a possible new idea and its mechanisms of operation, the key +words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", +"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the issue submission +are to be interpreted as described in RFC 2119. + + +Finally, and just as a call back to the first point, realize just because we +might not rush to implement something, doesn't mean that we don't want to +implement it! We would rather take the time to do something right the first +time, then hurriedly apply a new idea, or a fix, only to have to patch it later. + + +## Branch of Code Submissions + +Unless you've been specifically directed otherwise, all submissions of code +should be against the `nightly` branch, so make sure any modifications are based +on Nightly. + + +## Copyright / Licensing + +You acknowledge that by submitting code to GNU social, you are licensing it under +the GNU AGPLv3 unless there is an extenuating circumstance where it would be +licensed differently (such as modifications to an external library we include +such as Stomp). + +You also acknowledge that unless you assign a copyright explicitly, it will be +assumed to be assigned to GNU social. + +Thanks for considering submission, and happy hacking! diff --git a/DOCUMENTATION/VERSIONING.md b/DOCUMENTATION/VERSIONING.md new file mode 100644 index 0000000000..b7f19a63e7 --- /dev/null +++ b/DOCUMENTATION/VERSIONING.md @@ -0,0 +1,17 @@ +# Versioning + +## Release cycle +We follow Semantic Versioning as defined on [https://semver.org/](https://semver.org). + +The GNU social platform has a monthly release cycle. That is, we only increment the version number on day 1 of each month. + +For GNU social plugins, we increment version number by commit. Plugins update have a propagation of the same type in the +GNU social's monthly version bump. + +If we have various patch type updates in a month, we only bump it by one in the end of the month. If in the same month +we have a minor too, we will only bump the minor value. + +# Lifecycle + +GNU social has 'dev', 'alpha', 'beta', 'rc' and 'release' cycles. We usually are in `dev` during summer. When we finish a `dev` cycle we release an `alpha` (`dev`s aren't tagged as releases). From `alpha` to `release` it depends on how perfect GNU social is after the end of the `dev` cycle. But we use the number after `alpha` instead of `patch` number for small bug fixes when in this cycle. When we finally go from a `r`elease `c`andidate to a `release`, we party... and we use semver for all the small changes until we start working in another `dev` cycle (usually on another summer). +